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. 

Create an integration user

This integration requires a user who can authenticate REST web service calls when injecting events.

This user needs to be able to work with events, but does not need to update administrative settings. While you can use the default Company Supervisor role to authenticate REST web service calls, the best method is to create a user specifically for this integration with the "REST Web Service User" role that includes the required permissions and capabilities.

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

Note: If you are installing this integration into an xMatters trial instance, you don't need to create a new user. Instead, locate the "Integration User" sample user that was automatically configured with the REST Web Service User role when your instance was created and assign them a new password. For this integration, you will need to add the Group Supervisor and Person Supervisor roles to the Integration User, but can otherwise skip ahead to the next section.

To create an integration user:

  1. Log in to the target xMatters system.
  2. On the Users tab, click Add.
  3. Enter the appropriate information for your new user. Because this user will affect how messages appear for recipients and how events will be displayed in the reports and Communication Center, you may want to identify the user as specific to Zendesk; for example:
    • First Name: Zendesk
    • Last Name: Integration
    • User ID: zendesk
  4. In the Roles area, add the REST Web Service User, Group Supervisor, and Person Supervisor roles.
  5. Click Add.
Make a note of the user credentials and details; you will 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 will be 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 Browse, and then locate the downloaded communication plan (.zip file).
  3. Click Import Plan.
  4. Once the communication plan has been imported, click Plan Disabled to enable the plan.
  5. In the Edit drop-down list, select Forms.
  6. For the Incident Alert - Notify Group form, in the Not Deployed drop-down list, click Enable for  Web Service.
  7. After you create the web service, the drop-down list label changes to Web Service Only.
  8. In the Web Service Only drop-down list, click Permissions.
  9. Enter the REST API user you created above, and then click Save Changes.
  10. Repeat steps 7-9 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 you created above (or, if you are using a trial instance, to "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.

Enable authentication

When the communication plan is imported into xMatters, the Integration Builder services do not have authentication configured. Enable authentication for the integration builder so that the endpoints cannot be triggered unless the caller authenticates with a user name and password.

To enable authentication, expand the list of inbound integrations, and then click Authentication Off. The Authentication dialog will display a randomly generated username and password. Make a note of these values (or copy them to a temporary text file). They will not be displayed again, but you will need them when configuring Zendesk, as described below.

Accessing 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 Only drop-down list, and then select Access Web Service URL.

 

  1. Copy the highlighted URL from the dialog box:

To get the Integration URL for an integration service:

  1. On the Integration Builder tab, expand the list of inbound integrations.
  2. Click the gear icon beside the integration service you want to target, and then select Integration URL.

  1. Copy the URL displayed in the dialog box:

 

 You will need the URL for each form and inbound integration service when you configure Zendesk.

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 user name used to authenticate inbound integrations. This is the user name you configured in the Enable Authentication section after importing a communication plan.

Example: j52ijih04h3c326d088j461h4h66ac

xMatters Inbound Integration Password

The password used to authenticate inbound integrations. This is the password you were assigned in the Enable Authentication section after importing a communication plan. If you did not copy this password, you can generate another one.

Example: +c^9$}rDFi/~FR{rY&pH

xMatters User Basic Authentication Credentials

The username and password of the xMatters REST user, 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