Guide: Create ServiceNow Incident Events in Compass Using Custom Webhooks

[#1]

Compass recently released an update to our Custom Webhooks for Compass app to support the Incident event type. Using this feature, you can now create a Custom Webhook to receive Incident events from ServiceNow.

This guide will walk through all of the set up steps needed in Compass and in ServiceNow to build this integration. Please note that some of these screenshots and instructions may be slightly different depending on your version of ServiceNow. 

Set up in Compass

If you have not already, install the Custom Webhooks for Compass app and navigate to the Webhooks page.

Step 1: Create a Webhook

• Click Create to add a new Webhook and choose Incident as its event type.
• Set a name and description and click Next

Step 2: Create payload mapping from ServiceNow to Compass

On the next screen, add the following payload mappings for each field:

• Incident state → .incident.state

• Incident ID → .incident.id

• Incident event URL → .incident.url

• Incident severity level → .incident.severity.level

• Incident severity label → .incident.severity.label

  • Incidents will appear on the timeline with their Priority from ServiceNow, i.e. "1 - Critical"

  • If you would prefer Incidents to appear only as an Icon on the component timeline, leave this mapping blank.

• Incident event name → .incident.name

• Incident event description → .incident.description

• Start time → .incident.startTime

• End time → .incident.endTime

• Update sequence number and Last event update: leave these blank, as we will be using the provided defaults for these fields.

Step 3: Map ServiceNow state and priority level to Compass

On the next screen, we will be mapping ServiceNow Incident states and their Priority level to their Compass equivalents.

Feel free to make any changes to these mappings to fit your individual workflow. If you have created any custom states in ServiceNow, be sure to map those values as well.

Suggested mappings for ServiceNow incident states:

• New → Open

• In Progress → Open

• Resolved → Resolved

• Closed → Resolved

• On Hold → Resolved

• Canceled → Deleted

Suggested mappings for incident Priority:

• 1 → ONE

• 2 → TWO

• 3 → THREE

• 4 → FOUR

• 5 → FIVE

Step 4: Map ServiceNow services to their Compass Components

On the next screen, we will be creating forwarding rules that will match services in ServiceNow to their corresponding Compass components.

• The location in the payload for this field will be .serviceName.

• For each component that you want to map, put the exact Name of the service in ServiceNow on the left, and its Compass Component ID on the right.

  • You can always come back to add or change component mappings at a later time. However, a component will not receive Incident events until it has a mapping on this screen.

Step 5: Save your webhook

Submit the form to save your webhook. Then click the Copy button on the main screen to copy the URL of your new webhook. 

Set up in ServiceNow 

Step 1: Configure an outbound webhook message

• Navigate to System Web Services → Outbound → REST Message

• Create a new global Outbound REST Message and name it "Compass Incident Webhook"

  • Paste the webhook URL that you copied from Compass as the Endpoint

After saving your new REST Message, open it again to edit it. View its HTTP Methods at the bottom of the page and click New to add a new HTTP Method: 

• Call this HTTP Method "Default POST" and set its HTTP Method to "POST"

  • Paste the webhook URL that you copied from Compass as the Endpoint

  • Click the HTTP Request tab to view and edit the message body

  • In the Content section, paste the following message template:

{
  "incident": {
    "state": "${state}",
    "name": "${incidentName}",
    "description": "${incidentDescription}",
    "id": "${incidentId}",
    "url": "${url}",
    "startTime": "${startTime}",
    "endTime": "${endTime}",
    "severity": {
        "level": "${severity}",
        "label": "${severityLabel}"
    }
  },
  "serviceName": "${serviceName}"
}

•  Save your new Outbound REST Message

Step 2: Configure a Business Rule to send your webhook message

Now that an outbound webhook message is configured, we need to add a Business Rule that will trigger this message to be sent whenever an Incident is created or updated.

• Navigate to System Definitions → Business Rules

• Create a new Business Rule:

  • Name it "Send Compass Webhook"

  • Set its Table to Incident

  • Check the boxes for Active and Advanced

  • In the When to run section, set it to run After any Insert or Update

• Next, click on the Advanced tab to configure the custom code that we will execute:

  • Set the Condition to true

  • In the Script section, copy and paste the following script. This script will build your outbound REST message using attributes from your Incident, and call the webhook we created in the first step:

(function executeRule(current, previous) {
    var responseBody;
    var status;
    var sm;
    try {

      // The name of your Outbound REST Message and Method must match exactly
      sm = new sn_ws.RESTMessageV2('Compass Incident Webhook', 'Default POST');

      // Set timeout of 10 seconds
      sm.setHttpTimeout(10000);

      // Build request body
      sm.setStringParameter('severity', current.priority);
      sm.setStringParameter('severityLabel', current.priority.getDisplayValue());
      sm.setStringParameter('state', current.state.getDisplayValue());

      // You must create a mapping of this service name to a Compass Component in the Custom Webhooks App
      sm.setStringParameter('serviceName', current.business_service.name);

      sm.setStringParameter('incidentId', current.sys_id);
      sm.setStringParameter('incidentName', current.short_description);
      sm.setStringParameter('incidentDescription', current.description);

      var url = 'https://' + gs.getProperty('instance_name') + '.service-now.com/' + current.getTableName() + '?sys_id=' + current.sys_id;
      sm.setStringParameter('url', url);

      // Convert datetimes from ServiceNow
      // See: https://www.servicenow.com/community/service-management-forum/how-to-convert-servicenow-ticket-created-date-in-to-iso-8601/m-p/390683
      var original = current.opened_at.toString();
      var dt = original.split(' ');
      var f = dt[0].split('-');
      var t = dt[1].split(':');
      var event = new Date(f[0], f[1] - 1, f[2], t[0], t[1], t[2]);
      var startTime = event.toISOString();
      sm.setStringParameter('startTime', startTime);

      if (current.resolved_at || current.closed_at) {
         var endDate = current.resolved_at || current.closed_at;
         var originalEnd = endDate.toString();
         var endDt = originalEnd.split(' ');
         var endF = endDt[0].split('-');
         var endT = endDt[1].split(':');
         var closedEvent = new Date(endF[0], endF[1] - 1, endF[2], endT[0], endT[1], endT[2]);
         var endTime = closedEvent.toISOString();
         sm.setStringParameter('endTime', endTime);
      } else {
         sm.setStringParameter('endTime', '');
      }

      // Send request
      response = sm.execute();
      responseBody = response.haveError() ? response.getErrorMessage() : response.getBody();
      status = response.getStatusCode();
  } catch (ex) {
     responseBody = ex.getMessage();
     status = '500';
  }
}(current, previous));

• Save your new Business Rule

Now whenever an Incident is created or updated in ServiceNow, it will send a webhook message to Compass. As long as a Compass component is correctly mapped to a service name in ServiceNow, it will receive Incident events on its timeline. 

Please reach out to Compass Support if you have any difficulties following this guide or setting up your Incident webhook! 

[__ Jimi Wikman]

Wow, this is a great and very extensive article!!

Thank you for sharing @April G !