Desk.com Integration Guide

The Desk.com PagerDuty App allows you to trigger incidents within PagerDuty. This allows you to send notifications to your team even if it’s after hours. The PagerDuty system allows you to define how and when members of your team should be notified. If you are having trouble completing the installation, please contact us.

Please note that if you’d like to 1) auto-resolve incidents in PagerDuty when a Desk.com ticket is closed 2) display the content of tickets in PagerDuty incidents or 3) push tickets with specific conditions to different escalation policy in PagerDuty, you will need to create a generic email integration. Instructions on the email integration can be found at the bottom of this integration guide.

Setting up the PagerDuty / Desk.com integration

In PagerDuty

    1. From the Configuration menu, select Services. 
    2. On your Services page:

      If you are creating a new service for your integration, click +Add New Service.

      If you are adding your integration to an existing service, click the name of the service you want to add the integration to. Then click the Integrations tab and click the +New Integration button.

    3. RS-Add-New-Service
      RS-Add-Integration-Existing-Service

    4. Select your app from the Integration Type menu and enter an Integration Name.

      If you are creating a new service for your integration, in General Settings, enter a Name for your new service. Then, in Incident Settings, specify the Escalation Policy, Notification Urgency, and Incident Behavior for your new service.

    5. Click the Add Service or Add Integration button to save your new integration. You will be redirected to the Integrations page for your service.
      RS-Integration-Settings
    6. Copy the Integration Key for your new integration: RS_API_pd_3

    In Desk.com

    1. To start Go to yourdesksite.desk.com/admin/apps, click the PagerDuty button (you’ll see an image like the one below). Click on the Install button and agree to the Terms of Service.
      Add the PagerDuty Desk.com App
    2. Accounts

      A Desk.com App Account is the name you’ll use to refer to this Custom Account when you use it in Actions and Rules (Steps 3 & 4 below). You’ll need to set a name for this account, select PagerDuty Token Auth as the Authentication Method and add the Integration key from your existing PagerDuty Account (See step 4 above). Click on the Create button once you’re done filling out the form.
      Setup the PagerDuty Action

    3. Actions Now, we’ll configure Desk.com to send out messages using your PagerDuty account. (Note: You’ll need to tell PagerDuty who to contact and how to escalate the message – you make this configuration within PagerDuty.) An Action is the actual message you’ll be configuring to send through Desk.com to your PagerDuty Account when a Rule fires that matches the conditions you set.
    4. An example of an action is the following – you can add Liquid variables (like {{case.id}}) to provide dynamic information about the current case (Make sure to click on Add Action when completed):
      Configure the action for the PagerDuty Desk.com App
      When fired, this Action will use the PagerDuty App to send a message to PagerDuty that a particular Desk.com case is updated. To trigger this action, we’ll need to attach it to a rule in Desk.com.
    5. Rules

      Business rules in Desk.com allow you to act without Agent intervention when certain conditions occur at Events specified for a case.Here’s an example rule, run on a “Case Updated” event:
      Configure the rule for the PagerDuty Desk.com App
      A Business Rule fires when a certain Event occurs (e.g. a Case is Updated) and the conditions specified for that case evaluate to be true. In our example, we’ll fire the rule to post the Case Updated message on an Updated Case Interaction with an All Condition requiring the label “Send to PagerDuty“, and then remove that label at the conclusion of that rule so that the PagerDuty Message will not be sent until that label is added again.In addition, this rule will run anytime (not just during Business Hours). You can use the Advanced Edit to make sure your rule is enabled, and you can also view this rule in the Admin > Case Management > Rules section of Desk.com’s Admin. Make sure to click on the Update button once you’ve completed filling out the form.

    Congratulations! Your Desk.com PagerDuty App should now be integrated with PagerDuty!

    FAQ

    What happens when everything works?

    When you update a case in Desk.com by adding the label “send to PagerDuty“, the Rule will evaluate to be true, and the Action will fire to send a PagerDuty Message using your PagerDuty account. PagerDuty will then take over and notify the contacts you’d like to notify as per the escalation policy that you specify in PagerDuty.

    How do I set up an email integration between PagerDuty and Desk.com?

    I.Create a Generic Email Service in PagerDuty

    Begin by creating a generic email service in PagerDuty. Go to Configurations>> Services>> + Add New Service.

    From there you’ll need to:

    1. Name your service
    2. Choose Integration via email
    3. Create an email integration address
    4. Pick an escalation policy
    5. Set your Incident Settings
    6. Click Add Service

    New_Service_-_PagerDuty

    II. Setup Notifications

    Next, navigate to the Admin section of your Desk.com instance and add a new theme within Notifications.

    1. Admin
    2. Cases
    3. Notifications
    4. + Add Theme

    Desk_com_Email_Parsing_Guide_-_Google_Docs

    Desk.com will ask you to name your new theme. Once you’ve done that, click Add.

    Theme

    Next, you’ll edit the email template by entering the email integration address you created in your PagerDuty service. The integration email address goes in the To field.

    Desk_com_Admin_--_Lauren_Burnett

    III. Create Rules in Desk.com

    Now, navigate to the Rules section of Desk.com. In the example below I’m going to tell Desk.com to send an email to PagerDuty anytime a new ticket is created.

    If you already have Rules created, you can simply edit them – or you can create a new rule by clicking + Add Rule.

    Desk_com_Admin_--_Lauren_Burnett-1

    When creating Rules, think about what type of tickets you want to push to PagerDuty – for example, you may only want to send tickets that have a certain priority to PagerDuty, or tickets assigned to particular groups. To do so, you’ll need to specify the conditions in the Desk.com rule.

    Once you’ve established the condition(s) in which a ticket should be pushed to PagerDuty, you’ll tell Desk.com to send an email to your PagerDuty integration address.

    Chose Send Notification Emails and chose the notification you previously created.
    Desk_com_Admin_--_Lauren_Burnett

    Since you’re going to be auto-resolving incidents in PagerDuty, you also need to set up a Case Resolved rule – this will send a notification to PagerDuty when a ticket has been resolved.

    Desk_com_Admin_--_Lauren_Burnett-1

    Desk_com_Admin_--_Lauren_Burnett

    Now that you have Desk.com configured, return to PagerDuty and set up your email parsing rules – these rules will allow PagerDuty to auto resolve incidents.

    IV. Set Up Email Parsing Rules

    To create email parsing rules, navigate to your Desk.com PagerDuty service and go to Edit.

    Desk_com_Email_Parsing_Guide_-_Google_DocsUnder Email Management chose Create and resolve incidents based on custom rules.

    Desk_com_-_PagerDuty

    For this particular demo, in the first rule you want PagerDuty to trigger an incident if a Desk.com ticket contains Status: New in the body. (Again, you may choose to specify different conditions based on your use case.)

    Desk_com_-_PagerDuty-1

    Next you’ll create the incident key which will be used to append new emails to existing ones. The incident key should always be a unique identifier that appears in both the trigger and recovery email.

    Desk_com_-_PagerDuty

    If you look at the example Open and Resolved emails from Desk.com, you can see that the subject line doesn’t change – so you’ll use that as the incident key.

    Desk_com_Email_Parsing_Guide_-_Google_Docs

    Once you’ve established your conditions and incident key, click +Add Another Rule

    Desk_com_-_PagerDuty

    Since you want PagerDuty to close incidents when the corresponding ticket has changed to resolved, you will use “Status: Resolved” as your condition, and the same incident key that was used in the previous rule.

    Desk_com_-_PagerDuty

    And there you go! PagerDuty will now auto-resolve incidents for your Desk.com integration. If you’d like to double check, you can view an incident’s Incident Log. For Case #29, you can see that PagerDuty auto resolved the incident.

    Incident__497_-_PagerDuty

    If you have questions or need additional assistance, please contact support@pagerduty.com.