Integrate with Zendesk

Before you begin

• It might also happen that a placeholder can be replaced by a data reference of the data provided in one of the previous steps. That's why it's a good idea to learn more about Data references.
• Generate a Zendesk API Key. For details, see Zendesk documentation.

Start a Next Matter workflow instance from Zendesk and complete a step

Prepare your Next Matter workflow

• Make sure that the first step in the workflow contains a form field to receive the ticket ID.
• Make sure that you have auto-naming enabled for the workflow. The name of the instance should be a data reference to the Zendesk ticket ID. You can enable auto-naming in the Trigger step configuration.

Set up a custom field for categorizing the ticket and the Next Matter instance ID

The purpose of the custom field is to provide an ID of the Next Matter instance so that Zendesk can update the process instance automatically.

1. In Zendesk go to Admin Center > Objects and rules > Fields.
2. Click Add Field and select Dropdown as the text type.

3. Create one or more fields for agents to choose from.

📘

You can use fields / categories that you already have. Additionally, you can make the fields end user editable if you want to allow users to select categories that then trigger Next Matter processes.

4. Save your changes.
5. Click Add Field again and select Text as the text type.
6. Give the field a meaningful name.

Your agents can either manually fill the process ID in each ticket but it's easier if you send the instance ID from the Next Matter workflow to Zendesk with an integration step.

{ 
"ticket": { 
   "custom_fields": [
       { "id": ZENDESK_CUSTOM_FIELD_ID, "value": "{Instance URL}"
 }   //the instance URL is a data reference; to get the custom field ID, go to Zendesk  Admin > Manage/Ticket Fields > edit. The ID will be listed at the top of the Ticket Field Edit page.       
    ] 
  } 
}

Add the field to the ticket form

1. Go to Admin Center > Objects and rules > Forms.
2. Click on the form which you'll use to start the workflow.
3. Drag and drop the newly created custom field from the right-hand side section to the form.

Set up a webhook

The webhook will activate the integration with Next Matter.

1. Navigate to Admin Center > Apps and Integrations > Webhooks.
2. Click Actions > Create Webhook.
3. Give the webhook a meaningful name.
4. In the Endpoint URL, enter https://integrations.nextmatter.com/g/zendesk/startprocesswithdata
5. Select POST as the method and JSON as the request format.
6. Select API key and enter the details:

• Header name: Authorization
• Value: API-Key NEXT_MATTER_API_KEY

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 workflow that you want to communicate with, you will need a separate trigger.

1. Navigate to Admin Center > Objects and rules > Triggers.
2. Enter a recognizable name for the trigger. We recommend basing the name on the type of update that you want to do in Next Matter.
3. Choose a Zendesk category for your trigger. We recommend creating a "Next Matter" category for all your Next Matter-related triggers.
4. Set up the conditions for your trigger. This defines when Zendesk contacts Next Matter. The trigger can be based on different events happening in your tickets. Note that there must be one condition to check if the Next Matter Instance ID field that you created before is not empty.

5. Add action and choose Notify webhook in the dropdown. Select the previously configured Next Matter webhook in the second dropdown.
6. The contents of the JSON body section might look like the following:

{
 "process_id": WORKFLOW_ID,
 "complete_step_data":{
       "step_id": ID_OF_THE_STEP_IN_THE_WORKFLOW_TO_SEND_THE_DATA_TO,
       "actions":[
          LIST_OF_FORM_FIELDS_AND_THEIR_INPUTS
       ]
}

Note that each type of form field requires a different type of input. See our API reference.

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

Where is the step ID

1. In your left-hand navigation, click the Workflows icon.
2. Hover over the follow-up workflow and click on the menu icon.
3. Click Edit workflow.
4. Click the step to which you'd like to send data.
5. Copy the step ID. It's the last number in the URL you see in your browser.