Validio integrates with ServiceNow to streamline incident management:

• Automatic incident creation and updating: Incidents detected in Validio automatically create or update incidents in ServiceNow. Incident types include data quality issues, source errors (such as failed polls), schema changes, and segmentation limit exceeded errors. Validio updates existing incidents for each type, grouped by source, if their status is Open in ServiceNow.
• Customizable routing: Notification rules filter incidents to ensure that you track only what matters to you.
• Bidirectional syncing: Status updates, changes to owner assignments, and comments sync automatically between both systems, keeping context and progress intact.

Prerequisites for Adding a ServiceNow Channel

This integration requires configuration in both ServiceNow and Validio.

• You need to have a ServiceNow account to configure the Validio channel connection and bidirectional syncing.
• You can configure authentication from Validio to your ServiceNow account with Basic Auth (username and password) or OAuth (client ID and client secret). These ServiceNow credentials must have the following permissions:
  • incident (read, write, create)
  • sys_choice (read)
  • sys_choice.* (read)

Create a Validio Channel for ServiceNow

To add a new notification channel for ServiceNow,

1. In Validio, navigate to Notifications > Channels and click + New channel.

2. Namespace: Select where the channel and its rules will be created.

3. Under Configuration, Webhook, and Authentication, complete the required fields.

   Field	Description
   Channel type	Select ServiceNow from the list.
   Name	Enter a unique identifier. You will reference this name when configuring notification rules for this channel.
   Application link URL	Enter the URL to your Validio application instance, for example: https://my-company.validio.io You will use this URL to configure the webhook in ServiceNow. Also, this URL is used by ServiceNow to link back to incident details in Validio.
   Webhook secret	Enter a secret value for this channel. This webhook secret is used to authenticate requests from ServiceNow to Validio when syncing incident statuses.
   Instance URL	Enter the URL to your ServiceNow account, for example: https://my-account.service-now.com
   Authentication type	Select OAuth or Basic Auth.
   Username	For Basic Auth, the username to log into ServiceNow.
   Password	For Basic Auth, the password to log into ServiceNow.
   Client ID	For OAuth, the client ID for authorizing requests to ServiceNow.
   Client secret	For OAuth, the client secret for authorizing requests to ServiceNow.

4. Click Fetch status mappings and close codes to retrieve incident statuses from ServiceNow. For bidirectional status syncing to work, you need to map the incident statuses in Validio to the corresponding statuses in ServiceNow.

   📘

   If you are unable to fetch the statuses, you can manually type in the values. However, the value you type in must exactly match an existing ServiceNow status.

   • Status mappings: For each of the Validio statuses, select or enter the corresponding ServiceNow status.
   • Close codes: For each of the Validio close codes, select or enter the corresponding ServiceNow close status.

5. (Optional) Test channel: Click to test the connection to ServiceNow. This will create a new incident in ServiceNow.

6. Click Create.

Get the Channel ID

Once the channel is created, open the details panel for the new channel. Find and copy the Channel ID. You will use this ID to filter for this specific channel when you create the Business Rule (webhook) in ServiceNow.

Configure ServiceNow to Send Updates to Validio

After you create the Validio channel for ServiceNow, you need to create a Custom Field and Business Rule in ServiceNow. You will configure the business rule with a custom webhook that sends relevant incident status updates to Validio.

📘

The following sections include breadcrumbs to help you find the relevant pages in the ServiceNow UI. The page's URL slug is also included in parenthesis--you can type this into the navigation menu's filter to find the page.

Create a Custom Field

Complete the following steps to add a custom field (dictionary entry), which allows you to track which incidents were created by Validio and which channel (if you have multiple channels from Validio) created the incident.

1. In the ServiceNow UI, navigate to All > System Definitions > Dictionary (sys_dictionary_list).
2. Click New to configure a new dictionary entry (new record).
3. Complete the following required information:
   • Table: Select Incident [incident].
   • Type: Enter String.
   • Column label, Column name: Enter a descriptive name, for example Validio Channel ID.
   • Max length: Enter a number above 25.
   • Check Read only.
4. Click Submit.

Secure your Webhook Secret

For security, we recommend adding a System Property for your webhook secret so that you can reference the property instead of writing out the secret in plain text.

To configure the system property,

1. In the ServiceNow UI, navigate to System Property (sys_properties.list).
2. Click New.
3. Complete the following information:
   • Name: Enter a descriptive identifier, for example "u_validio.secret_name".
   • Type: Select Password2.
   • Value: Paste in the Webhook secret you set for the ServiceNow channel in Validio.
4. Click Submit.

Create a Business Rule

Complete the following steps to add a business rule with custom JavaScript that will send incident status updates to Validio. You will also add a filter to ensure the incident is related to a valid channel ID ("Validio Channel ID" is not empty). If you have multiple channels, you can add a filter for each channel in the same business rule configuration.

1. In the ServiceNow UI, navigate to All > Business Rules (sys_script_list).
2. Click New.
3. Complete the following information:
   • Name: Enter a descriptive identifier, for example "Validio Webhook for Channel".
   • Table: Select Incident [incident].
4. Check Advanced to enable additional configuration options.
5. In the When to run tab, configure a filter to ensure that the incident is related to a valid channel ID:
   • When: Select before.
   • Order: Enter a number, for example 100.
   • Filter Conditions: Choose the field, operator, and value to set the filter condition to "Validio Channel ID is <channel-id-from-validio>", where <channel-id-from-validio> is your ServiceNow channel ID in Validio. Refer to Get Channel ID.
6. In the Advanced tab's Script field, replace the template code with the provided script below. Make sure the values for VALIDIO_ENDPOINT and secret are valid. If you don't want to paste the webhook secret in plaintext, refer to Secure your Webhook Secret.

(function executeRule(current, previous) {
  const VALIDIO_ENDPOINT = "<VALIDIO-APPLICATION-LINK-URL>/servicenow-webhook";
  const secret = gs.getProperty("u_validio.secret_name"); // Or paste plaintext
  const channelId = current.getValue("u_validio_channel_id");

  if (!channelId || !current.changes()) {
    return null;
  }

  function getEmailFromRef(ref) {
    return ref && !ref.nil() ? ref.email.toString() : null;
  }

  function getEmailByUsername(username) {
    if (!username) {
      return null;
    }

    var user = new GlideRecord("sys_user");
    user.addQuery("user_name", username);
    user.query();

    return user.next() ? user.getValue("email") : null;
  }

  var changes = {};
  if (current.incident_state.changes()) {
    changes.incident_state = current.getValue("incident_state");
  }
  if (current.assigned_to.changes()) {
    changes.assigned_to = getEmailFromRef(current.assigned_to);
  }
  if (current.comments.changes()) {
    changes.comments = current.comments.getJournalEntry(1);
  }

  if (Object.keys(changes).length === 0) {
    return null;
  }

  var payload = {
    sys_id: current.getValue("sys_id"),
    channel_id: channelId,
    operation: current.operation(),
    updated_at: current.getValue("sys_updated_on"),
    updated_by: getEmailByUsername(current.getValue("sys_updated_by")),
    changes: changes,
  };

  try {
    var rm = new sn_ws.RESTMessageV2();
    rm.setEndpoint(VALIDIO_ENDPOINT);
    rm.setHttpMethod("POST");
    rm.setRequestHeader("X-Validio-Secret", secret);
    rm.setRequestBody(JSON.stringify(payload));

    var response = rm.execute();
    var status = response.getStatusCode();

    gs.info(
      "Incident webhook sent for " + current.number + " with status " + status,
    );
  } catch (e) {
    gs.error("Error sending incident webhook: " + e.message);
  }
})(current, previous);

7. Click Submit.