Launch Next Matter processes directly from Zendesk

Next Matter integrates seamlessly with Zendesk in two directions. In this integration tutorial you can learn how to trigger a Next Matter process directly from the Zendesk agent interface by categorizing the ticket with a custom field and setting up an automation rule based on that custom field. You will also receive a reply from Next Matter so that your agents have all context required.

Step 1: Zendesk: Set up a custom field for categorizing the ticket

The purpose of the field is to map your tickets to the right Next Matter process(es).

In Zendesk, navigate to Admin --> Ticket Fields --> Add Field --> Dropdown

Provide a name that you can recognize (e.g. "Trigger Next Matter Process") and add field values that correspond with the Next Matter processes that you want to trigger.

Example: If you want to manage master data change requests and GDPR compliance requests in Next Matter then you can add two fields like shown in the screenshot.

Hit save and note the custom field id for the field that you just created by clicking on the custom field once more.

Note for power users: It is possible to use existing fields / categories that you already have. Additionally, you can make this end user editable if you want to allow users to select categories that then trigger Next Matter processes immediately.

Step 2: Zendesk: Set up a custom field for the Next Matter instance URL

The purpose of the second custom field is to receive the URL to the Next Matter instance, so that your agents can track the request progress in Next Matter.

Add another custom field with the type text (navigate to Admin --> Ticket Fields --> Add Field --> Text)

The field can be called "Next Matter instance URL" or something else that you can recognize. The remaining settings can be left in the default state.

This is not required to make the integration work, but strongly recommended for added transparency.

Step 3: Add the fields to the right ticket forms

Your agents need to see the newly created fields, this can be achieved by adding it to the right forms.

Navigate to Admin --> Ticket Forms --> //Click on the right form

Drag and drop the newly created custom fields from the right hand side to the form.

Note: If you have more than one form then you need to add it to all of them.

Step 4: Zendesk: Set up an extension to activate the integration with Next Matter

Zendesk needs to know how it can communicate with Next Matter. For that you will configure an Extension within Zendesk

Navigate to Admin --> Extensions --> add Target
Give a recognizable name for the Extension. For example "Next Matter - Create Instance"
Fill the URL field with the Next Matter endpoint
https://integrations.nextmatter.com/g/zendesk/createinstance/
Choose Method POST and Content Type JSON
Tick the Check Box "Basic Authentication" and fill username and password (You can get an API-Key from Next Matter Support)
```
Username: Api-Key
Password: %%INSERT YOUR NEXT MATTER API KEY%%
```

The result will look like this

Step 5: Zendesk: Set up a trigger

Zendesk needs to be configured to send the right data at the right time to Next Matter. For that you need to configure a Trigger within Zendesk. For each process that you want to start in Next Matter, you will need a separate Trigger.

Navigate to Admin --> Triggers --> Add Trigger
Choose a recognizable name for the trigger. We recommend to base the name on the type of process that you want to start in Next Matter. For example if you start your "Customer Claim" process, you can name the trigger "Next Matter - new Customer Claim"
Choose a category for your Trigger. We recommend to create a "Next Matter" category for all your Next Matter related triggers.
Set up the conditions for your Trigger. This defines when Zendesk will contact Next Matter to start a new process. Common setup (see screenshot)
1. The custom field with the Next Matter categories is set to a certain value
2. The custom URL text field is not set yet, that avoids duplicate entries
Add action and choose "Notify Target" in the dropdown. Select your previously configured Next Matter Extension in the second dropdown
Copy the following code into the "JSON body" section. Replace the processid placeholder with the id of the Next Matter process that you want to trigger. You can find that ID if you access your process inside Next Matter (see screenshot).

{
"ticketId": "{{ticket.id}}",
"processId": %%INSERT PROCESS ID HERE%%
}

Test: When configured correctly, a Next Matter process will be launched with the ticket id as the name of the process whenever you set the according category in the custom field and save it.

Step 6: Send information back to Zendesk from Next Matter with the URL

To make sure that your agents can see the launched Next Matter process, take the following steps to send back the instance URL.

In your target Next Matter process create a new Integration step as the first step in the process and click on "Settings" on the newly created step.

Choose Method PUT and as URL enter the API endpoint of Zendesk that you want to use. For example to update a ticket you would use

https://{{your zendesk subdomain}}.zendesk.com/api/v2/tickets/{{instance_name}}

Add a header with Key "Content-Type" and Value "application/json". Add another header with Key "Authorization" and use this value

Bearer %%YOUR ZENDESK OAUTH TOKEN%%

Copy the following code into the body. Please replace the id placeholder with the Field ID of the Ticket field that you want to update in Zendesk. You can find that ID under Admin > "Ticket Fields" in Zendesk (see previous steps)

{ 
"ticket": { 
   "custom_fields": [
       { "id": %%insert Field ID here%%", "value": %%insert value here%% }           
    ] 
  } 
}

FAQ

Is it possible to do more things with the ticket than updating the custom field?

Yes of course. You can find the full API documentation here linked here

Is it possible to call additional data from the ticket?

Yes of course, you can find more information on that topic here in our knowledge base: Create custom user variables that contain parsed responses of integration steps | Next Matter Help Center

One example: If you have configured a previous step to get ticket details from Zendesk, you can automatically take the ticket id from that step by using Next Matters "data-referencing" capability. You can also use this functionality to update the ticket with values that were stored in previous process steps.