ServiceNow

ServiceNow can be used as a point of triage for newly detected data issues. ServiceNow provides rich reporting and workflow capabilities to ensure nothing falls through the cracks and that all issues are addressed in a timely manner. The integration between Monte Carlo and ServiceNow is effective at sending newly identified Monte Carlo Incidents to become ServiceNow Incidents in close to real time.

Experience

When an Incident from Monte Carlo is sent to ServiceNow, a link to the ServiceNow Incident will show on the Incident page and the Incident Feed. In addition, you can filter on the Incident Feed just for Incidents with an associated ServiceNow Incident.

It is also possible to sync the state of an incident in ServiceNow back to the incident status in Monte Carlo.

Integration Setup

Only the cloud version of ServiceNow is supported. To set up this integration, an Account Owner must go to Settings > Integrations. In the Notifications and Collaboration section, click Create and select ServiceNow. You can authenticate using OAuth client credentials or with a username and password. You will need:

• Instance name: this is the yourcompany piece of as https://yourcompany.service-now.com.
• Display name: this gives a superficial name to the integration within Settings, e.g. “ServiceNow production”.
• Client ID: client ID for authorizing requests to ServiceNow if authenticating via OAuth.
• Client secret: client secret for authorizing requests to ServiceNow if authenticating via OAuth.
• Username: user name to log in to ServiceNow. Incidents in ServiceNow will be created with this user.
• Password: password for that User ID. Here is how to set a password in ServiceNow.

You can integrate multiple ServiceNow environments if desired. When configuring Incidents to be sent to ServiceNow in Notification Settings, you will indicate which ServiceNow environment it should be sent to.

Configuring Inbound OAuth Client Credentials Grant

Please follow this guide when configuring ServiceNow to support Inbound OAuth Client Credentials grant. Double check that:

• glide.oauth.inbound.client.credential.grant_type.enabled property exists and is set to true
• The OAuth Application is configured with an OAuth Application User which will be used as the user that creates the incident and has the required permissions for the integration.

You can verify your setup is correct by running the following command on the command line:

curl -X POST https://<instance name>.service-now.com/oauth_token.do \
     -d 'grant_type=client_credentials' \
     -d 'client_id=<client ID>' \
     -d 'client_secret=<client secret>'

Notifications Setup

Once setup is complete, ServiceNow is available as a recipient in Notification Settings. When Monte Carlo sends a notification to ServiceNow, it will create a ServiceNow Incident.

When configuring notifications to be sent to ServiceNow, you have the ability to configure default values for any fields that are required to create a ServiceNow Incident. If you do not provide default values for all of your required fields, then a ServiceNow Incident will not be successfully created.

When configuring default values for any required fields, format them as:

• Field names: lower case with spaces as underscores. Example: input Service offering as service_offering
• Field values: for dropdowns, input an exact match to the desired value. However, if the desired value is a reference to another table, you may need to include a reference id, like 8fa3bbe947713110cf43ad8b136d4316

You can click 'Test Notification' to send a sample payload to ServiceNow. If the test is successful, it will create an example ServiceNow incident. If it fails, the test will return an error describing which required fields need to be populated or which field values were not accepted. Note: if you've provided default values for any non-required fields, the test may still be successful even if values for the non-required fields are rejected.

Syncing Status from ServiceNow Incidents back to Monte Carlo Incidents

Syncing the states of ServiceNow incidents back to Monte Carlo Incidents is optional and requires additional configuration.

Map your ServiceNow incident state values to Monte Carlo statuses

• Within the integration create/edit page, toggle Sync ServiceNow incident state to incidents to on
• Since states in ServiceNow are highly customizable, the user is asked to manually type the specific ServiceNow incident state values that should update the Incident status in Monte Carlo. Note that if you intend to use our default Business Rule script to set up your ServiceNow webhook (see next section), you must specify the incident state value (an integer ID) and not the label (text).

• 

• The status will sync when the incident state is updated in ServiceNow. A status update from within Monte Carlo does not have any impact on the state of a ServiceNow incident.
• Note: if an Incident has multiple ServiceNow incidents associated with it, then Status syncing is disabled for that incident. This is to avoid conflicting status updates.

Configure a webhook to send ServiceNow incident updates back to Monte Carlo

ServiceNow does not provide webhook functionality by default, so you must create a Business Rule running custom JavaScript to send incident state updates to the Monte Carlo webhook.

• When you first save your ServiceNow integration after toggling Sync ServiceNow incident state to incidents, you will get a webhook URL. You will also be able to see this URL if you go back to edit the ServiceNow integration.
• In the ServiceNow UI, click the All tab and then navigate to Business Rules
• Click New and select the table Incident
• Check the Advanced box to enable additional required options
• In the When to run tab select When: after, check just the Update box, then click Add Filter Condition and select Incident state with changes
• In the Advanced tab Script box, either paste the script included at the end of this session, or write a custom script that sends the same payload structure. The "webhook_event": "servicenow:incident_updated"entry is required. Make sure to update the webhook URL in the script to match the webhook URL you configured earlier.
  • If you write a custom script, you can define your own logic for passing ServiceNow incident states to Monte Carlo. If you implement custom state strings, make sure to use those in the status mapping you configured on the ServiceNow integration above.
• Create the webhook Business Rule
• Expect latency of 30-60 seconds between ServiceNow and Monte Carlo.

(function executeRule(current, previous /*null when async*/ ) {
  try {
    var r = new sn_ws.RESTMessageV2();
    // TODO: Update this URL to your unique webhook URL --------------------------\/\/\/\/\/\/\/\/
    r.setEndpoint("https://integrations.dev.getmontecarlo.com/webhooks/servicenow/your-webhook-url");
    r.setHttpMethod("post");

    var payload = {
      "webhook_event": "servicenow:incident_updated",
      "current": {
        "sys_id": current.getValue("sys_id"),
        "sys_updated_by": current.getValue("sys_updated_by"),
        "sys_updated_on": current.getValue("sys_updated_on"),
        "incident_state": current.getValue("incident_state")
      },
      "previous": {
        "sys_id": current.getValue("sys_id"),
        "incident_state": previous.getValue("incident_state")
      }
    };
    var body = JSON.stringify(payload);

    gs.info(body);
    r.setRequestBody(body);

    var response = r.execute();
    var httpStatus = response.getStatusCode();
  } catch (ex) {
    var message = ex.message;
    gs.error("Error message: " + message);
  }

  gs.info("Webhook target HTTP status response: " + httpStatus);
})(current, previous);