Zendesk Alerts

We recommend you add a user in Zendesk specifically for the workflow. xMatters uses their credentials to authenticate requests to Zendesk, and this user appears as the author of comments added by xMatters. The user needs to be an agent with permission to update tickets, and needs to have either password access or token access configured on the Admin > Channels > API page in Zendesk.

xMatters needs to know a user's Zendesk ID so it can map the assignee coming from Zendesk to a user in xMatters and send notifications to the people who need to be notified.

1. Create a custom user property with the name Zendesk User ID.
   • In this instance, we didn't select Required because not all users in this xMatters deployment have a Zendesk ID.

2. Click Save.

The next step is to create any new users and update the Zendesk User ID field in the profiles of any new or existing users to hold their Zendesk ID.

1. On the Users tab, select the user you want to update and click their Profile tab.
2. Enter their Zendesk ID in the Zendesk User ID field and click Save Changes.
   • To find a user's ID in Zendesk, go to Manage > Agents in the Admin section. Open the record for the user then copy the user ID portion of the URL.
     

To update multiple users, you can also export a list of users to a .csv file (make sure you do this after you add the custom field), add the Zendesk user IDs to the custom field column in the .csv file, and then use the User Upload feature to load that information into xMatters.

Add your groups to xMatters, making sure to use the same name assigned to the group in Zendesk. This is the name xMatters looks up when notifying a group. When you add your group, you can create shifts, add members, and set up escalations and rotations.

If you change the name of a group in Zendesk, make sure you update it in xMatters.

xMatters uses the Zendesk endpoint to update and add comments to tickets. To set up the endpoint, you need the credentials of the Zendesk user you set up.

1. On the Flow Designer tab in the workflow, click the Components menu and select Endpoints.
2. Select the Zendesk endpoint and copy the URL of your Zendesk instance into the Base URL field (for example, https://your-company.zendesk.com).
3. Enter the username and password of the xMatters user in Zendesk.
   • If you're using password access, make sure you come back here and update the password if the user's password changes.
   • If you're using token access, append /token to the username (for example, xmattersuser@your-company.com/token) and use the API token as the password.

4. Click Save.

If you want to use a different authentication method, you need to create a new endpoint and point any steps in the flow using the existing endpoint to the new one (look for the Zendesk logo to find the steps that update or add comments to Zendesk).

You need to retrieve and copy the URLs for each of the triggers you want to target from Zendesk.

1. Click the Flow Designer tab and open the Notify Group canvas.
2. Locate the Notify Group trigger — it should be the topmost trigger on the canvas.

3. Double-click the trigger (or hover over it and click the pencil icon).
4. Select the authentication method you want to use to initiate the trigger.
   • If using URL authentication, select the authenticating user to update the trigger URL. When a request to the URL is received, the trigger and any connected steps run using the permissions of that user. You might want to change this to an integration user specific to Zendesk.
5. In the Initiation section, click Copy to copy the trigger URL to the clipboard.

6. Copy the trigger URL — you'll use it to set up the Notify Group webhook in Zendesk.
7. Repeat the steps above for the Notify Assignee and the Terminate Events flows.

If you labeled the custom field exactly Zendesk User ID, there's nothing you need to do. However, if you change the label, you need to update the value of the Assignee ID custom field name constant to match.

1. Click the Components menu and select Constants.
2. Select the Assignee ID custom field name constant and check that the value matches the label you gave the custom field.

The first step is to add a webhook for each trigger URL from xMatters. To create a webhook for the Notify Group trigger URL:

1. In the Zendesk Admin section, go to Apps and integrations > Webhooks, and then click Create Webhook.
2. On the Create Webhook page, select Trigger or automation, and then click Next.
3. Give the webhook a title (for example, Notify Assignee) and then paste the trigger URL in the Endpoint URL field.
4. Make sure Request method is set to POST and Request format is set to JSON.
5. Select the Authentication type you want to use. If using Basic authentication, enter the username and password of an xMatters user with permission to initiate the trigger (or the API key and secret). Because this user appears as the initiator or submitter of alerts from the integration (in messages, alert reports, etc.), you might want to create an integration user specific to this workflow.
6. Click Create webhook.
   1. You can navigate back to the Webhooks page or click Finish setup. You'll create the connections for these webhooks in the next section.

7. Repeat the steps above for the Notify Assignee and Terminate Events trigger URLs.

The next step is to create a Zendesk trigger that initiates each webhook. The instructions provide the basic settings required to initiate an alert in xMatters when a ticket is created and assigned to a user or group. You can add additional conditions to fine-tune when the trigger is run (for example, a condition for "Priority is Greater than Normal" so an alert is only created for High or Urgent tickets).

1. In the Zendesk Admin section, go to Objects and rules > Triggers.
2. Click Add trigger.
3. Enter a trigger name and description that tells what the trigger does (for example, Ticket is created and assigned).
4. Set the conditions for the trigger. In the Meet ALL of the following conditions section, set the conditions:
   • Notify Assignee: "Ticket Is Created" AND "Assignee Is not -"
     
   • Notify Group: "Ticket Is Created" AND "Assignee Is -"
     
   • Terminate Events: "Ticket Is Updated" AND "Status is Greater than Pending"
     
5. In the Actions section, select Notify active webhook and select the appropriate webhook (notify groups, notify assigned or terminate events).
6. Copy the payload into the JSON body field.
7. Click Create.

Copy the payload into the JSON body field when configuring the Zendesk triggers for this workflow.

{

 "Ticket ID": "{{ticket.id}}",

 "Subject": "{{ticket.title}}",

 "Description": "{{ticket.description}}",

 "Status": "{{ticket.status}}",

 "Initiator": "{{ticket.requester.name}}",

 "Priority":"{{ticket.priority}}",

 "Type": "{{ticket.ticket_type}}",

 "Group Name": "{{ticket.group.name}}",

 "Assignee": "{{ticket.assignee.name}}",

 "Assignee ID": "{{ticket.assignee.id}}",

 "URL": "{{ticket.url}}"

}

The person responding to the notification has the following response options:

• Acknowledge: Assigns the xMatters alert to the responder and stops notifying any other targeted recipients (if a group was targeted). xMatters adds an internal comment to the ticket.
• Add a Note: Adds the user's comment to the alert and stops notifying them. xMatters continues processing the alert for this user and any other targeted recipients (if a group was targeted). xMatters adds the note as an internal comment on the ticket.
• Resolve: xMatters terminates the alert and stops notifying all targeted recipients. The ticket is changed to Solved and xMatters adds an internal comment to the ticket.
• Escalate (Notify Group only): Immediately escalates the alert to the next targeted recipient (if a group was targeted). xMatters adds an internal comment to the ticket.

If there are existing alerts related to the ticket, xMatters terminates them before creating a new alert.

An internal comment is added if xMatters could not map a Zendesk user ID to an xMatters target name. In addition, comments are also added to the Zendesk ticket when the following alert activities occur:

• an alert is created in xMatters,
• a user adds an additional comment using xMatters,
• the alert is escalated, either manually or because of a timeout configured for the group,
• xMatters could not immediately notify any of the targeted recipients.

If you want to turn off any of the alert activity comments, see Disable comments for alert activities. You can also turn on updates when a notification is delivered — or couldn't be delivered — to a device.

By default, the workflow adds comments to the Zendesk ticket for various alert activity triggers in xMatters. You can disable some or all of these. Updates for device delivery alerts are disabled by default; you can turn these on, if needed.

1. Open the flow that is generating the alert activity comment you want to turn on or off (either the Notify Assignee or Notify Group flow).
2. Look for the icon of the associated trigger on the canvas and double-click it (or click the pencil icon when you hover over it).
3. Click the Enabled toggle to set it to Disabled (or click the Disabled toggle to set it to Enabled).
4. Click OK.

The trigger and any steps connected to it are disabled or enabled.

Unless you're modifying the fundamental functionality of the workflow, or using it as a template to build your own, you shouldn't need to modify the workflow constants.

• Assignee ID custom field name: This is the name of the custom field in xMatters that stores the Zendesk ID of users. xMatters uses the value in the custom field to map the assignee value in a Zendesk payload to an xMatters user, so we can find the right person to notify.
• Language Suffix: The two-letter language code to append to text properties when the workflow performs a search for them (for example, common codes are en, es, fr, ru, pt, and zh). The search for text properties needs to know what language the property is in, so this suffix is appended to the property name when searching.
• Open Event Statuses: A comma-separated list of xMatters alert statuses that are considered open. This is used to determine if there is an open alert related to the ticket that needs to be terminated.
• Ticket ID Property Name: The workflow property that holds the Zendesk ticket ID. This is used to determine whether the alert relates to the ticket (for example, when determining if there are any existing alerts related to the ticket that need to be terminated).
• Workflow Name: This holds the workflow name. It's used to narrow the results when searching for related alerts that need to be terminated. You only need to update this field if you rename this workflow. If this field is empty, xMatters terminates all alerts that have a matching Ticket ID value.