ServiceNow

This integration supports:

• Converting a Monte Carlo alert into a ServiceNow incident, or linking an existing incident. Multiple ServiceNow incidents may be linked or created from a single alert in Monte Carlo.
• Automatically sending notifications directly to ServiceNow via audiences.
• Syncing status updates from ServiceNow incidents to the corresponding alert in Monte Carlo.

Integration setup

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.

User permissions

In order for the integration to work properly, the ServiceNow users must have the following permissions:

• incident (read, write, create)
• sys_dictionary (read)
• sys_dictionary.* (read)
• sys_choice (read)
• sys_choice.* (read)
• sys_glide_object (read)
• sys_glide_object.* (read)

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>'

Creating a ServiceNow incident from a Monte Carlo alert

To create a ServiceNow incident from the alert page, click the Add ServiceNow incident:

Once clicked, a drawer opens. If creating a new ServiceNow incident, you can input the Summary and Description. Summary and Description are pre-populated with information about the alert and a URL to link back to the alert in Monte Carlo.

Click Create and you should be given a confirmation that an incident has been created. This process can be repeated to link multiple ServiceNow incident to the alert.

Automating ServiceNow incident creation with Audiences

You can add ServiceNow as an audience recipient. Any alert that is sent to that audience will automatically create a ServiceNow incident.

To get started, navigate to Notifications and click Create audience. Add a recipient and integrate it with your ServiceNow account:

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

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 alerts

Syncing the states of ServiceNow incidents back to Monte Carlo alerts 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 Monte Carlo alert status 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 a Monte Carlo alert 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 Monte Carlo alert status, 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);