Zendesk Integration v3.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.

Are you using the Zendesk steps in Flow Designer?

Flow Designer - our drag-and-drop, visual workflow builder - includes steps to easily add Zendesk to your incident management workflow. You can find help on using the Zendesk steps in the xMatters On-Demand help.

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 notifies the on-call resource on their preferred 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 outbound integration types (event status, delivery status, and response) are active by default and authenticate with the xMatters user set up in Zendesk.

A note about this integration

The xMatters app for Zendesk was built on an earlier version of the Zendesk Application framework. Zendesk has deprecated this version of the framework and removed apps using it from their app marketplace. We're working on updating our app to use the latest version. In the meantime, we've attached a communication plan that you can use to initiate events in xMatters when a Zendesk trigger is initiated.

The Engage with xMatters and Who's On Call features depend on the xMatters app, so they are currently unavailable.

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.

Add an xMatters user in Zendesk

Before you get started, you need to configure an user in Zendesk for the integration. You'll use this later when configuring the Zendesk endpoint in xMatters. 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 identify the user as specific to xMatters; for example, use "xMatters-Zendesk" as the name.
    • 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.

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. See Create an integration user for more information.

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 to 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.

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 Incident Alert - Notify Assignee 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. Add a new "Zendesk" endpoint.
  3. Enter your Zendesk instance in the Base URL field.
  4. Set Authentication Type to Basic, and then enter the credentials (email address and password) of the user you created in Zendesk for this integration.
  5. Click Save Changes.
    • You can delete the existing Zendesk endpoint.

Determine the integration URLs

Each integration has its own URL that you need to copy so you can target it from Zendesk.

To get the integration URL:

Since these URLs are only used to configure the xMatters app, you can skip to the next section.

  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. 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, select URL Authentication then select the integration user as the authenticating user. 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

Note: The xMatters app is currently not available for download from the Zendesk app marketplace. We're working on updating the app and getting it back in the marketplace. For the interim, skip ahead to the next section.

  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.

Populate the xMatters User ID field

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

When an event targets the Incident - Notify Assignee integration, 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:
{
  "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:
{
  "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

Note: The Engage with xMatters feature relies on the xMatters app, which is currently not available for download from the Zendesk app marketplace. We're working on updating the app and getting it back in the marketplace.

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

Note: The Who's On Call feature relies on the xMatters app, which is currently not available for download from the Zendesk app marketplace. We're working on updating the app and getting it back in the marketplace.

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.
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:
"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