Overview

Sifflet natively integrates with your ServiceNow incident management workflow. When a Sifflet monitor fails, Sifflet can automatically create a ServiceNow incident, ensuring that data quality issues detected by Sifflet are tracked in ServiceNow and preventing critical problems from being missed.

Setting Up the Integration

📘

Integration requirements

The ServiceNow integration process requires actions in both Sifflet and ServiceNow. A ServiceNow user with OAuth permissions needs to create an OAuth Application Endpoint, and a user with the ServiceNow Information Technology Infrastructure Library (ITIL) role needs to grant permissions to Sifflet. Different users can perform these tasks.

To connect Sifflet to your ServiceNow account, follow these steps:

1. In Sifflet, go to Settings (via the sidebar) and click Collaboration Tools. Then, in the ServiceNow section, click Connect to ServiceNow.
2. Copy the redirect URL displayed in the integration pop-up. You need this URL later.
3. In ServiceNow, create an OAuth Application Endpoint:
   1. In ServiceNow, create an OAuth application endpoint in your account. (Refer to the ServiceNow documentation here for guidance.)
   2. For the Redirect URL parameter, paste the URL you copied in step 2.
   3. You can leave other parameters at their default values.

      📘

      Important Note (ServiceNow behavior update):
      ServiceNow changed the default for the Restriction Scope field when creating an OAuth application. It may default to Securely Scoped, which can prevent successful authentication with Sifflet.

      If you encounter connection errors during setup, check the OAuth app’s Restriction Scope in ServiceNow and set it to Broadly Scoped before retrying.

      🚧

      OAuth refresh token lifespan

      ServiceNow OAuth refresh tokens have a default lifespan of 100 days. Sifflet recommends increasing the lifespan of the token created for Sifflet.

      If you decide to keep the default lifespan, you'll need to reconfigure the integration every 100 days.

4. Complete the Sifflet Integration:
   1. Return to Sifflet and continue creating the ServiceNow integration (following the same process as in step 1).
   2. Enter the following details in the integration pop-up:
      1. Your ServiceNow instance URL (e.g., https://yourinstance.service-now.com)
      2. Your OAuth application client ID
      3. Your OAuth application client secret

         📘

         ServiceNow Role Requirement

         The user creating the ServiceNow integration in Sifflet must have ServiceNow access with either the ITIL role assigned or sufficient permissions to create incidents. This enables Sifflet to create and update incidents via the OAuth application.

   3. Click Save. Sifflet redirects you to the ServiceNow OAuth portal. Click Allow to grant Sifflet access to your ServiceNow account.

      📘

      Sifflet has the same permissions as the ServiceNow user who approves the OAuth request.

5. (Optional) To enable incident status synchronization between Sifflet and ServiceNow incidents, see the Status Synchronization section for setup instructions.

Sifflet now creates the integration. If you see an error message instead of a success message, check the configuration settings for any problems. The error message provides details to help you troubleshoot.

Creating Incident Templates

With your ServiceNow integration configured, you can use incident templates to customize the ServiceNow incidents created by Sifflet. Templates let you specify the values for various incident fields, ensuring each incident has the required context.

Once you've defined the custom ServiceNow fields and their values within the template, click the Send test incident button to test your configuration. This creates a sample incident in your ServiceNow environment, which you can delete after verifying that the process is working correctly.

📘

Double-check that the test incident contains all the custom fields and their values

Make sure the test incident contains all the values and custom fields specified in the template before saving.

📘

Custom field value types

Ensure that the values you insert for the different custom fields match the field's type in ServiceNow. In case of a type mismatch, the incident creation fails.

Configuring Sifflet Monitors to Trigger ServiceNow Incidents

Via the UI

When creating a new monitor or editing an existing one, use the Notification method section to choose whether Sifflet creates a ServiceNow incident if the monitor fails. Here, you can also select the ServiceNow incident template the monitor will use.

Via Data-Quality-as-Code

When creating a new monitor or editing an existing one, using Sifflet's Data-Quality-as-Code YAML syntax, you can configure it to create a ServiceNow incident by adding the following parameter:

- kind: ServiceNow
	enabled: true
	templateName: <Name of the ServiceNow template>

Interacting with ServiceNow Incidents via Sifflet Incidents

When Sifflet creates an incident, if the failing monitor is set up to create a corresponding ServiceNow incident, Sifflet automatically creates that ServiceNow incident. You'll see a dedicated button on the Sifflet incident page linking to the ServiceNow incident, and Sifflet records the creation event in the Sifflet incident activity log.

📘

Unlinking a ServiceNow incident

If you want to unlink a ServiceNow incident and a Sifflet incident, you can use the dedicated Unlink ServiceNow incident button:

Incident Status Synchronization

Enabling incident status synchronization between Sifflet and ServiceNow allows you to ensure consistency across the different incidents and maintain an up-to-date status for incidents both in ServiceNow and Sifflet.

Benefits of Incident Status Synchronization

Once you enable the synchronization:

• Sifflet incidents reflect the latest status of the corresponding ServiceNow incident.
• The Sifflet incident activity timeline includes the history of status changes of the ServiceNow incident.

Enabling the Synchronization

To enable incident status synchronization, follow these steps:

1. In the ServiceNow integration pop-up, toggle "Enable status changes sync from ServiceNow to Sifflet" to on.

2. Copy the webhook URL provided by Sifflet.

3. Provide a secret and then store it with the webhook URL.

4. Configure incident states mapping by associating ServiceNow incident states to the desired Sifflet incident states.

5. Create a business rule in your ServiceNow instance (documentation) with the following configuration:

   1. Check the Advanced box

   2. Table: Incident [incident]

   3. Configure the When to run tab as follows:

      1. When: after

      2. Order: You can keep the default value

      3. Check the Update box

      4. Filter Condition: Incident state + changes

         

   4. In the Advanced tab, replace the boilerplate code with the following script (in line 5 replace <YOUR_SIFFLET_WEBHOOK> with the webhook URL copied in step 2 above, and in line 7 replace <YOUR_SIFFLET_SECRET> with the secret created in step 3 above.):

      JavaScript

      (function executeRule(current, previous /*null when async*/) {
      
          try {
              var r = new sn_ws.RESTMessageV2();
              r.setEndpoint("<YOUR_SIFFLET_WEBHOOK>"); // Sifflet Webhook URL
              r.setHttpMethod("post");
              var secret = "<YOUR_SIFFLET_SECRET>"; // The secret key shared between your app and ServiceNow
      
              var payload = {
                  "webhook_event": "servicenow:incident_updated",
                  "current": {
                      "number": current.getValue("number"),
                      "incident_state": current.getValue("incident_state"),
                  },
                  "previous": {
                      "number": previous.getValue("number"),
                      "incident_state": previous.getValue("incident_state"),
                  }
              };
              var json_payload = JSON.stringify(payload);
      
              var digest = new GlideDigest();
              var hashHex = digest.getSHA256Hex(secret + json_payload);
              var signature = "sha256=" + hashHex;
      
              r.setRequestHeader("x-hub-signature", signature);
              r.setRequestBody(json_payload);
              var response = r.execute();
              gs.info("Webhook sent to Sifflet. Status response: " + response.getStatusCode());
      
          } catch (ex) {
              gs.error("General error in Sifflet webhook process: " + ex.message);
          }
      
      })(current, previous);

Troubleshooting

A ServiceNow Field I Set in the Template Is Empty in the Sifflet-Created ServiceNow Incident

If a field in a Sifflet-created ServiceNow incident is empty, even though you set a value in the template, verify that the value meets the ServiceNow field's requirements. These requirements may include more than just the value's type.