Desk.com Integration with xMatters On-Demand

 

Contents

Introduction

Configure xMatters

Configure Zapier 

Test the integration

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 for integrating Desk.com with xMatters.  The integration focuses specifically on automating notification when a New Case is created.

This integration is built using Zapier.  When a new case is opened in Desk.com (and its status is set to Open), case details are sent to xMatters via Zapier using REST / JSON.  Then notifications are sent to the defined recipients.  

Once notifications are delivered, recipients can also respond by either acknowledging or escalating.  

The Value:  This integration is can be leveraged as a lightweight service desk to manage incidents and contacts, either internally or externally.

Extending the integration

This document is intended to provide a brief, helpful overview of the Desk.com-xMatters On-Demand integration process. The included examples and sample communication plan are designed to get your integration up and working quickly, and not intended to be a final solution. It is expected that you will want to modify the integration on your own deployment to suit your specific business needs, and use the powerful feature set provided by xMatters On-Demand. 

Integration created and supplied by Jessie DeCarlos

Before you start...

You will need some things before you start:

  • An account and login information for Zapier
  • An account and login information for Desk.com
  • Access to your xMatters deployment, and the ability to create communication plans

Configure xMatters

The first step in the integration process is to configure xMatters (you'll need some of the information in this process to configure the other components). 

Create a REST API user

To authenticate REST web service calls when injecting events, you'll need a user with the correct permissions in xMatters. This user needs to be able to work with events, but does not need to be able to update administrative settings. The best way to create a user for this integration is to have a dedicated "REST Web Service User" role that includes the permissions and capabilities. If this role does not exist in your deployment, you will need to create it, or ask your xMatters Client Success Manager to create it for you. (For detailed procedures about creating the role, see Authentication and Permissions.)

In the following example, this role is named "REST Web Service User".

To create a REST API user:

  1. Log in to the target xMatters system.
  2. On the Users tab, click the Add New User icon.
  3. Enter the appropriate information for your new user.
  4. Assign the user to the REST Web Service User role.
  5. Click Save.
  6. On the next page, set the web login ID and password. 

Make a note of these details; you will need them when configuring the Zapier side of the integration.

Create users and groups that will receive notifications

Before xMatters can send someone a notification, you need to make sure that their contact information is available. You can set up a user in xMatters using your own information to receive a test notification, or you can add the people and teams from your environment using the web user interface.

For testing this integration, you should add a user to xMatters with an email device that you can access so you can respond to the test notifications.

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

Import the communication plan

This integration includes a sample communication plan that is already configured with response options and other required settings for Desk.com.

To import the communication plan:

  1. Download the attached .zip file to your system.
  2. In the target xMatters system, on the Developer tab, click Import Plan.
  3. Click Browse, and then locate the downloaded file.
  4. Click Import Plan.
  5. Once the communication plan has been imported, click Plan Disabled to enable the plan.

  1. In the Edit drop-down list, select Forms.
  2. For the New Case form, in the Not Deployed drop-down list, click Create Event Web Service.
    • After you create the web service, the drop-down list label will change to Web Service Only.

  1. To enable the messaging form, in the Web Service Only drop-down list, click Form.
    • The label of the drop-down list will change to Form and Web Service.
  2. Click Form and Web Service > Permissions.
  3. Enter the REST API user you created above, and then click Save Changes.
  4. To get the web service URL for a form, in the Form and Web Service drop-down list, click Access Web Service URL. Copy the highlighted URL at the top of the dialog box.
    • Note that the Access Web Service URL option appears twice in the drop-down menu. Ensure that you click the first option, just below Create Event Web Service.
    • You'll need this URL to configure Desk.com.

The included form contains seven text-based properties: id, cleanid, description, priority, status, and subject:

The "id" property is for a full path to the API, which is required for callbacks, and the "cleanid" property is the Case ID number needed for the messages. 

For a list of the fields that can be passed through the integration, see the Desk.com Help section at http://dev.desk.com/API/cases/#fields.

The integration is configured to leverage the properties in the New Case form layout, and some of the standard features such as Sender Overrides and a hard-coded recipients list.

It also includes a generic set of English notification templates for email/push, SMS, and voice:

The default response options are for Acknowledge and Escalate, based on the use case of on-call notifications for a small department. (Additional responses can be added easily.)

The following images illustrate how the default messages appear on different devices:

 

Configure Desk.com

Now that you've configured xMatters, it's time to configure Desk.com.

Create Zap #1: New Case

  1. Login to Zapier. Once logged in, click Make a New Zap.
  2. In Step 1: Choose a trigger and action:
    • In the "When this Happens" area, select Desk as the trigger. For the action, select New Case.
    • In the "Do This" area, select xMatters as the trigger. For the action, select Create Event.

  1. In Step 2: Select a Desk account, you will need to log in to Desk.com and Grant Access to Zapier. Then click OK
  2. In Step 3: Select a xMatters account, you will need to log in to your xMatters' instance using the REST API User you created earlier. Then click Continue.
  3. In Step 4: Filter Desk triggers, under Custom Filters, click Add Filter:
    • In the Field drop-down list select Statuses with the Condition of open.

  1. In Step 5: Match up Desk Case to xMatters On-Demand Event, copy the web service URL from the New Case form from the communication form you imported earlier and paste it into the Web Service URL field.
    • Add the Desk properties and map them to their xMatters equivalents as shown in the following image:

 

  1. In Step 6: Test this Zap, use Sample #1 as a test. 
  2. In Step 7: Name and turn this Zap on, name the Zap (e.g., "Desk.com - New Case").

Create Zap #2: xMatters callback to Desk.com 

The next step is to configure xMatters to send a callback to Desk when an event is triggered through Zapier. In this instance, when a message is delivered to an xMatters recipient, a callback will POST via Zapier using Web Hook and create a new case note in Desk.com with a "Delivered" message.

For this step, you will need the URL to which Web Hook should post the callback. It should resemble the following, where "yoursite" is the host name of your Desk.com instance:

https://yoursite.desk.com/api/v2/cases/:id/notes

You will also need to replace ":id" with the ID of the

To create a new Zap for callbacks:

  1. In Zapier, click Create a New Zap.
  2. In Step 1: Choose a trigger and action:
    • In the "When this Happens" area, select xMatters as the trigger. For the action, select New Response.
    • In the "Do This" area, select WebHook as the trigger. For the action, select POST.
  1. For Step 2: Select xMatters account, select the login you previously created from the drop-down list. Then click Continue.
  2. In Step 3: Select a Web Hook account, just click Continue.
  3. In Step 4: Filter xMatters triggers, in the drop-down list, select Delivery Status for  "Status of service delivery", and then click Continue.
  4. In Step 5: Match up xMatters On-Demand Device Delivery to Web Hook POST, paste the Web Hook URL described above.
  5. Remove the ":id" portion of the Web Hook URL.
  6. Click Insert (x) Fields.
  7. Copy the Callback URL from the pop-up dialog box, and then click OK, I did this.
  8. Log in to your xMatters On-Demand instance, and navigate to the Developer tab.
  9. Select the communication plan you uploaded previously and click Edit > Forms.
  10. On the Forms page, click Edit > Callbacks.
  11. Select Delivery, and then paste the URL you copied from the clipboard into the URL field. 

  1. Click Save.
  2. Click Edit > Layout.
  3. On the Layout tab, click the gear icon beside the id property, and then select Include in Callbacks.
  4. Go back to Zapier and click OK I did this., but do NOT close the pop-up dialog box.
    • To retrieve the needed resources from xMatters, you need to initiate a message.
  5. In xMatters, click the Messaging tab, and then click New Case.
  6. In the id field, enter the case ID of an existing case in Desk.com.
  7. At the bottom of the form, ensure that you have selected a recipient with a device that you can access, and then click Send Message.
  8. In Zapier, wait until the message has been processed. Once Zapier sees the event and changes the dialog box options, click All Done. (You may need to click through twice.)
    • Once complete, Zapier will display a list of resources.
  9. In the drop-down list, select Event Property ID.
    • This action should insert the orange Event Property ID 'pill' where the ":id" parameter was in the URL.
  10. In the Payload Type section, select json.
  11. In the Data section add an entry for body, and set the message to Alert delivered to Recipient on Device.
    • To insert the Recipient and Device entries, click the Insert (x) Fields button and select them from the drop-down list.
  12. In the Basic Auth section, add your Desk.com username and password, and then click Continue.
  13. For Step 6: Test this Zap, click Test xMatters trigger.
    • To verify that the configuration has worked, go to Desk.com and locate the case you targeted for update (in step 19, above), and make sure a delivery note has been added.
  14. And finally Step 7: Name and turn this Zap on, name the Zap (e.g. Salesforce - Case Notification Delivery Status), and then click Turn Zap on.

Create Zap #3: Message Response

In this section, you will configure xMatters to place a callback when an event is triggered through Zapier and back to Desk.com. In this instance, when messages are acknowledged or escalated by a recipient, xMatters will place a callback via Zapier, using Web Hook, and POST a new case note in Desk.com with the recipient's response.

To configure a message response callback:

  1. Log in to Zapier and create a new Zap; in Step 1: Choose a trigger and action:
    • In the "When this Happens" area, select xMatters as the trigger. For the action, select New Response.
    • In the "Do This" area, select Web Hook as the trigger. For the action, select POST from the drop-down list.
  1. For Step 2: Select xMatters account, select the login you previously created from the drop-down list, and then click Test this account. Once successful, click Continue.
  2. In Step 3: Select a Web Hook account, just click Continue.
  3. In Step 4: Filter xMatters triggers, click Add Filter, and then click Field. Click Copy to clipboard to copy Zapier's REST Callback URL (e.g. https://zapier.com/hooks/catch/oj7z99/). Click OK I did this.
  4. Go to your xMatters On-demand instance, navigate to the Developer tab, and click Edit > Forms for the Salesforce Desk engine. On the New Case form, click Edit > Callbacks.
  5. Select Response, and then paste the URL you copied from the clipboard into the URL field. Click Save.
  6. Click the Messaging tab and then, in the menu on the left side of the screen, click New Case. In the id field, enter the case ID of an existing case in Desk.com. Select a test Recipient, and then click Send Message.
    • Once the notification has been received, you will need to respond with Acknowledge.
  7. Go back to Zapier and click OK I did this.
    • Zapier will now look for response message that will be sent in the Callback. This may take a few minutes.
  8. Once successful, you will just need to click OK I did this again for a 2nd time. You will not have to send another message in xMatters.
  9. Once completed, select Response from the Custom Filters drop-down list and Exist from the Condition list.
  10. In Step 5: Match up xMatters On-Demand Response to Web Hook POST, paste the Web Hook URL described at the beginning of Create Zap #2, above.
  11. Remove the ":id" portion of the Web Hook URL, and then click Insert (x) Fields. and select Event Properties ID.
  12. In the Payload Type section, select json.
  13. In the Data section add an entry for body, and set the message to A reply of Response has been received from Recipient.
    • To insert the Response and Recipient entries, click the Insert (x) Fields button and select them from the drop-down list.
  14. In the Basic Auth section, add your Desk.com username and password, and then click Continue.
  15. For Step 6: Test this Zap, click Test xMatters trigger. Once the test is successful, click Continue.
  16. And finally Step 7: Name and turn this Zap on, name the Zap (e.g. Salesforce - Case Response), and then click Turn Zap on.

xMatters / Salesforce Properties

Status Product
Case Reason  Case ID
Description Owner Name
Company Case Type
Priority Account Name
Case Number Subject

Test the integration

To test the integration :

  1. Create a new case in Desk.com.
  2. Make sure the case's status is set to Open

Download resources

xMatters Salesforce Communication Plan Package - zip Download
Video Demo of the integration at work. Download

 

 

 

 

Have more questions? Submit a request

1 Comments

  • 0
    Avatar
    Jhopwood

    I think we might need to update this documentation as the Desk.com interface has changed quite a bit. 

     

Please sign in to leave a comment.
Powered by Zendesk