Zendesk Integration v2.0

Contents

Introduction

Configure xMatters

Configure Zendesk

Test the integration

Troubleshooting

Add properties

Download resources

 The information in this article is the intellectual property of xMatters and is intended only for use with xMatters products by xMatters customers and their employees. Further, this intellectual property is proprietary and must not be reused or resold.

Introduction

This article provides installation, configuration, and implementation details when integrating xMatters On-Demand with Zendesk.

How it works

Zendesk is a cloud based customer service platform that gives substantial power with little to no coding. Coupled with the power of xMatters alerts, this integration:

  • Quickly identifies and notifies the on-call resource on a variety of devices.
  • Allows for voice, SMS, and push messages to agents.
  • Allows agents to reply with "Assign to me" from their device and take ownership of the ticket.

The integration to Zendesk is initiated by Triggers in Zendesk, which decide when to send an event to xMatters. These triggers build a payload and send to an Extension that holds the URL and authentication information for communicating to the xMatters Integration Builder. 

Once the payload reaches the Integration Builder, xMatters creates an event and notifies the target group. Or, if the Assignee form was targeted, xMatters makes an API call to the Zendesk Users API to retrieve the xMatters user name and map it to the Assignee's User fields, and then creates the event. In either case, current active events for this ticket ID are terminated.

After the event is created, users are notified:

  • If a group was targeted, members have the option to respond with "Assign to me", which looks up the xMatters user name and uses it to set the Assignee to the user's Zendesk ID and then ends the event. Recipients can also choose to respond with "Escalate", which immediately notifies the next user in the escalation.
  • If the event targeted the Assignee form, recipients can respond with "Accept" which ends the event. 

All three callback types (event status, delivery status, and response) are active by default and authenticate with the xMatters user set up in Zendesk.

New in this version are the Engage with xMatters and Who's On Call components, which rely on the xMatters REST API to enable users to communicate with colleagues on an ad hoc basis and to view current xMatters shift information without leaving Zendesk. The Engage with xMatters feature adds three new forms to the communication plan, with corresponding inbound and outbound integrations that allow Zendesk to stay up-to-date with user interaction from xMatters.

Features and updates 

This version of the xMatters On-Demand and Zendesk integration includes a Certified Zendesk App that you can install into your Zendesk instance to help streamline the installation and configuration process. The app includes packaged extensions to use with your Zendesk triggers that will communicate with the xMatters inbound integrations, and a new sidebar application that launches the Engage with xMatters and Who's On Call features. 

Engage with xMatters

The Engage with xMatters feature allows users to provide updates, request help, or start a conference bridge with colleagues from other teams to assist with an existing ticket. 

For example, a support team member has taken ownership of a ticket, but needs help from the database team to resolve part of the problem. Instead of assigning the ticket to someone else and losing the benefits of ownership, the support person can use the Engage with xMatters feature to contact the primary on-call person in the database group. xMatters continues to update the internal notes of the ticket within Zendesk so the the support team member still receives real-time updates on whether someone else has started work - and who that person is. If there is a group or person that does not exist in Zendesk (but does in xMatters), the support team member can still find them using the Engage with xMatters feature and bring them up to speed directly.

The support team member could also choose to use the Engage with xMatters conference bridge feature to connect with multiple groups through hosted or external conference bridges and work on a solution together. 

Who's On Call

The Who's On Call feature displays current xMatters shift information within the Zendesk interface - no need to open a new browser window or login to xMatters.

For example, a support team member wants to place a direct call to someone on the database team to confirm a solution. Instead of looking up the team in a company directory or calling a data center and hoping someone picks up, the support person can use the Who's On Call feature to see who is the right primary on-call person in the database group to contact. 

Configure xMatters

The first step in setting up your integration is to configure xMatters.

Download the integration package

To begin, download the communication plan attached to this article; it contains everything needed for this integration. 

Set up an integration user

This integration requires a user who can authenticate REST web service calls when working with events – these permissions are provided by the "REST Web Service User" role in xMatters.

To successfully execute some of the tasks for this integration, the integration user requires some additional permissions in xMatters, as indicated below.

For Free and Trial customers, your system has an "Integration User" already configured with the REST Web Service User role, so you don't need to burn up an extra user from your limited supply. For this integration, you need to add the Group Supervisor and Person Supervisor roles to the Integration User. After you've done that, make sure you've changed this user's password from the default, then you're good to go.

For everyone else, we recommend you create a user specifically for this integration because this user appears as the initiator or submitter of events from the integration (in messages, the Communication Center, event reports, etc.). Give this user the "REST Web Service User" role and a profile that lets you easily identify the user as specific to the integration – for example:

  • User ID: zendesk
  • First name: Zendesk
  • Last name: Integration

For this integration, you also need to add the Group Supervisor and Person Supervisor roles to this user.

Note: Make sure you keep the user ID and password of this user handy. You'll need them when configuring other parts of this integration. 

Create users and groups that will receive notifications

The integration notifies the Assignment Group defined in the ticket unless an Assignee is designated, in which case the Assignee is notified. The group names in Zendesk must match the group names in xMatters; however, if the user name in Zendesk does not match the user name in xMatters, you can configure an "xMatters User Name" user field as described below.  

You can create multiple groups and users at once using the EPIC feature. 

Import the communication plan

The next step is to import the communication plan into xMatters.

To import the communication plan:

  1. In the target xMatters system, click Import Plan from the Developer tab.
  2. Click Choose File, and then locate the downloaded communication plan (.zip file).
  3. Click Import Plan.
  4. Click the Edit drop-down list for the plan, and select Access Permissions.
  5. Add the integration user, and then click Save Changes.
  6. In the Edit drop-down list, select Forms.
  7. For the Engage with xMatters - Conference Bridge form, in the Web Service drop-down list, click Sender Permissions.
  8. Enter the integration user, and then click Save Changes.
  9. Repeat steps 6-8 for the remaining forms in the plan.

Configure endpoints

After you have imported the communication plan, you need to set the authentication for the xMatters and Zendesk endpoints.

  1. From the communication plan, click the Integration Builder tab, and then click Edit Endpoints.
  2. Assign the "xMatters" endpoint to the integration user.
  3. Update the "Zendesk" endpoint to use Basic authentication, and then enter the credentials (email address and password) of a Zendesk user that has permission to update tickets. 
  4. Click Save Changes.

Determine Web Service URLs

Each form and integration service has its own URL that you can use to target it from Zendesk.

To get the web service URL for a form:

  1. In the communication plan, on the Forms tab, click the the Web Service drop-down list beside a form, and then select Access Web Service URL.

ZendeskFormURL.png

  1. Copy the highlighted URL from the dialog box:

Configure inbound integrations

You need to update the authentication for each inbound integrations, then retrieve the URLs to configure Zendesk. (The following steps assume that you are using the URL Authentication option, which is the default setting for this communication plan. For more information about these options, see Inbound integration service authentication.)

To configure an inbound integration and retrieve its URL:

  1. In the Integration Builder, expand the list of inbound integrations.
  2. Click the name of the integration to view its details.
  3. Scroll down to How to trigger the integration at the bottom of the page, and select the integration user as the authenticating user (make sure the authentication method is set to URL authentication). The URL trigger is updated to reflect the new user.
    • To be able to select the integration user, you need to be a supervisor of that user and the user needs to be assigned to the REST Web Services role.
  4. Click Copy beside the Trigger field:

CopyURL.jpg

Configure Zendesk

Now that you've configured xMatters to integrate with your system, it's time to configure Zendesk to integrate with xMatters. The following sections require you to log into Zendesk with an administrator account and access the Admin settings page.

Install the Zendesk App

  1. Log in to Zendesk as an administrator, and open the Admin menu (click the gear icon on the lower left of the screen).
  2. Under Apps, click Marketplace
  3. Search the marketplace for "xMatters"; in the results list, click the xMatters badge.
  4. Click Install App.
  5. Configure the settings on the Installation screen as shown in the table below (you can adjust these settings once the app is installed).
  6. Click Install to save your settings.
ZenDesk setting xMatters setting

xMatters Base URL

The URL of your xMatters instance; do not include the https:// portion.

Example: mycompany.abc.xmatters.com

Engage with xMatters - Provide Update URL

The web service URL of the "Engage with xMatters - Provide Update" form.

Example:
https://mycompany.abc.xmatters.com/api/integration/1/functions/ed0369d3-d7b4-433b-8736-94da4a0fa33d/triggers

Engage with xMatters - Request Assistance URL

The web service URL of the "Engage with xMatters - Request Assistance" form.

Engage with xMatters - Conference Bridge URL

The web service URL of the "Engage with xMatters - Conference Bridge" form.

xMatters Incident - Notify Assignee URL

The integration URL of the "Incident - Notify Asignee" inbound integration

xMatters Incident - Notify Group URL

The integration URL of the "Incident - Notify Group" inbound integration

xMatters - Terminate Events Endpoint URL

The integration URL of the "Terminate Events Endpoint" inbound integration

 

xMatters Inbound Integration Username

The username used to authenticate inbound integrations (the username of the integration user).

xMatters Inbound Integration Password

The password used to authenticate inbound integrations (the password of the integration user).

xMatters User Basic Authentication Credentials

The username and password of the xMatters REST user in Zendesk, in the format username:password and Base64-encoded. You can create this value by following the instructions below:

  • Go to https://www.base64encode.org/.

  • In the “Encode to Base64 format” area, type the username and password of the xMatters REST user account, separated by a colon in the format username:password, for example, restUser:UDQw9awK

  • Click Encode, and copy the result.

Example: emVuZGXzayp7ZW5kZXnRmTE=

Note: After the app is installed, you can update or modify settings using the Manage option in the Apps menu. When updating settings, you may need to disable and then re-enable the integration for the packaged Zendesk targets to use your new settings.

Add an xMatters user

You can use an existing administrator account in Zendesk,  or create a specific user for xMatters to use when authenticating into Zendesk to update tickets. 

To create a user in Zendesk:

  1. In the Manage menu, click People.
  2. Click add user, and then type a name and email address in the Name and Email fields. Because this user will be displayed in Zendesk as the authenticating user, you may want to use this opportunity to identify the user as specific to xMatters; for example, use "xMatters-Zendesk" as the name.
    • Note: The email address must not be currently in use and must be valid. A link for resetting the password will be sent to this address. 
  3. In the Role drop-down list, select Agent, and then click Save
Once the password has been set, make sure you update the fields in the Zendesk endpoint in the Integration Builder endpoints as explained above.   

Populate the xMatters User ID field

In cases where your Zendesk user names (email addresses) do not match with user names created in xMatters, you can update the new "xMatters User ID" field to store the corresponding xMatters user name for your Zendesk users. xMatters User ID is a custom user field in Zendesk.

When an event targets the Incident - Notify Assignee integration service, a call is made back to Zendesk to retrieve the xMatters User ID. Additionally, when a user responds with "Assign to me" to a notification from xMatters, the response callback integration service will look up the Zendesk user's ID based on the xMatters User ID field. 

For details on how to populate the xMatters User ID with values, see the Zendesk Support site. 

Add triggers

Zendesk uses triggers to hold the rules for when to initiate the web service calls detailed in the extensions. These are logical conditions that build a payload and will vary from help desk to help desk.

Note: When developing your triggers, be careful to ensure the alerts are being fired at the relevant times.

To begin creating triggers, click the Triggers option under the Business Rules menu on the Admin page.

The following examples illustrate the settings for some potential triggers.

Trigger One

Title: Send Incident to Group via xMatters

Meet all of the following conditions:

  • Ticket: is Updated
  • Ticket: Priority is Urgent
  • Other: Current user is not xmatters
  • Ticket: Group changed
  • Ticket: Status is not Solved

Perform these actions:

  • Notifications: Notify target - xMatters Group
  • JSON Body:
  1. {
      "properties": {
        "Description": "{{ticket.description}}",
        "ID": "{{ticket.id}}",
        "Status": "{{ticket.status}}",
        "Title": "{{ticket.title}}",
        "Assignee": "{{ticket.assignee.name}}",
        "Assignee ID": "{{ticket.assignee.id}}",
        "Group Name": "{{ticket.group.name}}",
        "Priority": "{{ticket.priority}}"
    
      }
    }
NOTE: The structure of this JSON body is very important. It is used by the Integration Builder to pass through the properties. You can add additional fields, but you must also add them to the layout of the relevant communication plan form. This payload adheres to the POST /trigger payload. 

Trigger Two

Title: Terminate xMatters Events for this Incident  

Meet all of the following conditions:

  • Ticket: is Updated
  • Ticket: Status Greater than Pending

Perform these actions:

  • Notifications: Notify target - xMatters Terminate Event
  • JSON Body:
  1. {
      "properties": {
        "ID": "{{ticket.id}}"
      }
    }

Note: The xMatters User Name field for the assignee can be referenced as

"Assignee xM User Name": "{{ticket.assignee.custom_fields.xmatters_user_name}}"

 

Test the integration

To test the integration, create or update a ticket that will satisfy the trigger rules defined above. 

Engage with xMatters

You can test the Engage with xMatters feature using an existing incident.

To engage with xMatters:

  1. With an incident open in Zendesk, click Launch xMatters.

  2. In the Engage with xMatters dialog box, choose the engagement type (Request Assistance or Provide Update), use the Recipients area to add the people or groups you want to notify and add the Subject and Message you would like to send.



  3. Click Send to send your message.

Who's On Call

To test the Who's On Call feature, open an existing incident, and then click Launch xMatters. In the dialog box, click Who's On Call:

To view the contact details for a particular user or group, click the Details link beside their name.

Troubleshooting

There are several places you can inspect when troubleshooting why an event is not sent to xMatters. 

Inbound to xMatters

First, in Zendesk, click the Show all events tab on a ticket that was expected to create an event. This will display an audit of all the actions that happened on each update. In particular, it will show what triggers fired. 

When expanded, the entry shows the Assignee was removed and the "Send Incident to Assignee via xMatters - Update" trigger fired:

The next place to look is the Integration Builder Activity Stream. While on the Integration Builder tab, expand the Inbound Integrations section, click the gear icon beside the intended integration service, and then click Activity Stream.

The Activity Stream contains the incoming (and for outbound integrations, the outgoing) request, any logging statements as well as the final event creation messages.  

Outbound from xMatters

For the two-way integration from xMatters to Zendesk, the primary source of logging is the Integration Builder Activity Stream for that particular integration.

For example, troubleshooting why a ticket was not assigned to a user after they replied with "Assign to me", check the Activity Steam for the Response Callback outbound integration.  

Add properties

Occasionally, business use cases will require additional properties to be included in the end notifications. Since the "properties" JSON structure is created in the trigger, the Integration Builder is used as a pass through and no additional work needs to be done there. 

To add additional properties (key/value pairs) follow these steps:

  1. In the communication plan in xMatters, create the property with a sensible name.
    • We recommend that you create these as text properties. Otherwise, care needs to be taken in ensuring the trigger generates the correct JSON format. 
  2. Add the new property to the layout of the appropriate form.
    • There is no limit to the number of properties on a layout so it won't hurt to add it to all forms. 
  3. Add the entry to the trigger JSON body.
    • Refer to the Zendesk trigger docs for details on how to refer to specific fields in the ticket. 
For example, if the new property was titled "VIP User" and the field was ticket.custom_fields.vip_user, then you would add a new line to the "properties" element:
  1. "VIP User": "{{ticket.custom_fields.vip_user}}",

Download resources

 

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk