Integration types

Next Matter can integrate with any system through integration steps, for example, to retrieve data and use it further in a process or to update data in a third-party system.

You can only connect integrations if you are a Next Matter admin.

Next Matter and an external application connect using HTTP requests. Each request is a step in Next Matter, called an integration step.

There are two types of integrations:

• No-code integrations: These integrations must be connected in the Next Matter portal in Automations library. When connected, you can select them directly as an Integration step, and in some cases, you might only need a few JSON details to configure the step.

• Custom integrations:
  • Advanced: You will find them in the Next Matter portal in Automations library. These integrations require you to give the 3rd party tool access to Next Matter, share login credentials when you connect them, and provide the endpoint and JSON request body when you use them in workflows. You will find database integration in this category, too. These integrations require you to enter a few more data items such as port, username, and password, and database hostname to connect.
  • Pro: These integrations require authorizing your API calls with 3rd party-generated credentials. It might be the API key or basic authorization. You can provide the authorization details when you configure the custom integration step in Next Matter alongside the endpoint URL and JSON request body. You can also make calls to Next Matter API. This will also require you to authenticate your call - this time with the Next Matter API key you can generate in Company > Next Matter API keys.

Ensure you have permissions to generate authentication credentials in Next Matter and the external app. If not, your company admin should be able to provide those.

No-code integrations

How to connect an integration

How to connect an integration

1. In the main navigation, go to Automations library.
2. Open the Integrations tab.

3. Search for your integration.
4. Click Connect in the integrations tile.
5. Provide the required data or consent to the app sharing data with Next Matter.

(Custom - Advanced only) When connected, the app shows in the Authorization dropdown inside any Custom integration step. Select the connected app so as not to authenticate every call you make.

Users and authentication

The authorization rights for the entire Next Matter workspace are tied to the user who is used to make the integration connection. For example, if you authorize Google Sheets, then Next Matter will ask you to select a user for the Google Sheets connection. As a consequence, Next Matter can interact only with the sheets to which this user has access.

Some companies create an email address and a user for all Next Matter system integrations, for example, [e-mail]. That way, it’s easier to manage system access rights across all Next Matter workflows.

How to disconnect an integration

Any admin can disconnect the integration. Workflows that use integration steps with that integration will no longer work until reconnected by an admin.

1. In the main navigation, go to Automations library.
2. Open the Integrations tab.
3. Search for your integration.
4. Click Disconnect for an integration.

Custom integrations

What are custom integrations for?

Custom integrations are used to connect several 3rd party tools that use REST API, or to call Next Matter API. Normally, these integrations are added and configured as you build a workflow as a custom integration step. With Custom integrations, you can connect most external tools and are not limited to the ones that you can connect within Next Matter.

How to connect custom integrations?

You can connect some custom integrations, such as PostgreSQL or Microsoft OneDrive, directly in Next Matter. If the integration you need is not on the list, you can connect it when you build your workflow.

To use custom integrations that you can’t connect directly in Next Matter, you’ll need the 3rd party app’s API key. If you’re not an admin, you can ask your IT department to generate those for you.

1. In the main navigation, go to Automations library.

2. Open the Integrations tab.

3. Search for your integration.

4. Click Connect in the integrations tile.

5. Provide the required data or consent to the app sharing data with Next Matter.

Users and authentication

The authorization rights for the entire Next Matter workspace are tied to the user who is used to make the integration connection. For example, if you authorize Google Sheets, then Next Matter will ask you to select a user for the Google Sheets connection. As a consequence, Next Matter can interact only with the sheets to which this user has access.

Some companies create an email address and a user for all Next Matter system integrations, for example, [e-mail]. That way, it’s easier to manage system access rights across all Next Matter workflows.

How to disconnect custom integrations?

Any admin can disconnect the integration. Workflows that use integration steps with that integration will no longer work until reconnected by an admin.

1. In the main navigation, go to Automations library.
2. Open the Integrations tab.
3. Search for your integration.
4. Click Disconnect for an integration.

How to build an integration step?

To use such an integration when building a workflow, do the following:

1. In your workflow, click + Add step.

2. Select Integrations > Custom integration step.

3. Click the step in the left-hand navigation and then click the cog wheel to configure the step.

4. Provide the required details:

   1. (1) The API method and the URL of the endpoint you’re calling. You might want to check the 3rd party developer documentation for the URL details.

   2. (2) Headers

   3. (3) Authorization header: it can be basic authentication or a token. You need to generate the details in the 3rd party app.

      If you’ve connected the app directly in Next Matter, select the connected app from the Authorization dropdown. No additional authorization is required.

   4. Payload (body of the request in JSON format): you might check the 3rd party developer documentation for any required parameters.

Test integrations

When you create an integration step, it’s a good idea to test the integration first before running the workflow instance.

1. Click Test Integration.
2. Use the generated test values or replace them with your own.
3. Click Start Test and see if it gives you a correct response. If not, you can always reconfigure the step and retry it.
4. When you get a positive result, click Done and work on the rest of the workflow.

Integration responses

Use the integration step response to troubleshoot failed steps or to extract specific variables (using JSONPath). To see the response body, click Show details.

Note that we only show responses up to 32KB. Larger responses are not shown, and an error “Response Body Size exceeded” is displayed. However, you can still use variables referencing the response details, or even the entire response.

Skip failed integration steps

When you configure an integration step, you can decide what to do if the connection fails. You can either:

• decide to skip the step and let the workflow continue
• pause the workflow at the step allowing the admin an option to skip or retry the step. A failed step will automatically send the admin and the tech lead notification to their Next Matter inbox and an email to their provided email address.

Debugging data in failed step email header

The email notification provides an admin or a tech lead with all the debugging data without the need to log in to the Next Matter app to investigate.

The email is enriched with the X-Custom-Data header that you can decode:

1. Open the email to view its source. For example:

   • In Gmail click the three dots (⋮) in the top right and select Show original.
   • In Outlook Web, click the three dots (⋮) and select View source.

2. Search for X-Custom-Data.

3. Copy the data in a base64 decoder. You can use this decoder (external link).

The decoded data might look like the following:

{
  "instance_id": 5977564,//Unique identifier for the workflow run
  "step_id": 328167, //Specific step that failed 
  "process_id": 16742, //Workflow ID
  "company_id": 330,
  "url": "https://app.nextmatter.com/app/live/5977564/step/328167",
  "status": null,
  "error": "Missing configuration. Configure the step and try again.", //Human-readable message
  "body": null,
  "debug_errors": {} //Detailed technical error information
}

The status and body information is displayed for custom integration steps, and debug_errors for most of our no-code steps.

Templates

Templates are ready-made custom integration steps that are displayed in your workflow.

To use a template, in your process click + Add step > Templates > 3rd party templates and pick a template you want to use.

When you have the template in your workflow, click Settings for every step it created and configure it. In most cases, you’ll need to enter the details in the placeholders in the Body of the step.

It might also happen that a placeholder can be replaced by a data reference of the data provided in one of the previous steps. To learn more about data references, see Data references.