​
Overview

Rootly’s ServiceNow integration leverages workflows to automatically create and update ServiceNow tickets. If you are unfamiliar with how Workflows function please visit our Workflows documentation first.

​
Workflows

​
Create a ServiceNow Incident

This workflow action creates a record in the Incident table (e.g. INC0010001) and links it to the Rootly incident record.

​
Update a ServiceNow Incident

This workflow action updates the data properties of an existing record from the Incident table (e.g. INC0010001).

​
Common Custom Fields

​
Major Incident

// Example create major incident (make sure acts_as_user is set) and ACL good (Cf. https://community.servicenow.com/community?id=community_question&sys_id=fae73aeb1b7370900b8a9979b04bcb1a)
{
  "assignment_group": "3De45d9ebc3b333200fe02c9bb34efc434",
  "major_incident_state": "proposed"
}

​
Work Notes

Work notes are internal comments that can be added to a ServiceNow incident. Work notes cannot be seen by customers.

{
 "work_notes": "{{ incident.events[0].event_raw }}"
}

​
Comment

Comments can be added to a ServiceNow incident and it can be seen by customers.

{
  "comments": "{{ incident.events[0].event_raw }}"
}

​
Add Configuration Item (CI) to Incident

Adding a configuration item (CI) to an incident is an awkward action due to technical limitations of ServiceNow APIs. To facilitate this action we will need to utilize Rootly’s HTTP Client workflow action to consolidate mutiple ServiceNow API calls into a single action.

The ServiceNow API we will use to add CIs to an incident is the Table API.

curl -X POST \
'https://<instance-domain>.com/api/now/table/task_ci' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <username:password>' \
--data '{
  "task": "<incident_id>",
  "ci_item": "<ci_sys_id>"
}'

Since ServiceNow API only allows one CI to be added per API call, we will use their Batch API to wrap multiple Table API calls together and leverage Rootly’s HTTP Client workflow action to carry out the call.

​
Name

This field is automatically set for you. You can rename this field to whatever best describes your action. The value in this field does not affect how the workflow action behaves.

​
URL

This is the endpoint of the ServiceNow Batch API. The value should be in the following format: https://<instance-domain>.com/api/now/v1/batch

​
Method

This is the API operation. In this case, select POST.

​
Header Parameters

These are the header parameters required by the Batch API. The values are configured in JSON format and includes the authentication token.

If you don’t want your username:password to be visible by non-Admins, you can store it as Secret variable in Rootly.

In this case, set to the following format:

//using exposed username:password
{
  "Accept": "application/json",
  "Content-Type": "application/json",
  "Authorization": "Basic <base64 encoded username:password>"
}

//using Rootly secret - this is the recommended method
{
  "Accept": "application/json",
  "Content-Type": "application/json",
  "Authorization": "Basic {{ secrets.service_now_key_encoded }}"
}

​
Query Parameters

Since this is a POST call, there will be no query parameters. Leave this field empty.

​
Body Parameters

The body is where we want to consolidate individual Table API calls into a single body.

Each body field of the individual API calls wrapped inside of the BATCH API have to be base64 encoded.

The format follows something like this:

//includes base64 encoding of body field
//this format is required to complete the API call
{
  "batch_request_id": "1",
  "rest_requests": [
    {
      "id": "11",
      "headers": [
        {
          "name": "Content-Type",
          "value": "application/json"
        }
      ],
      "url": "/api/now/table/task_ci",
      "method": "POST",
      "body": {<base64 encode of request body>}
    },
    {
      "id": "12",
      "headers": [
        {
          "name": "Content-Type",
          "value": "application/json"
        }
      ],
      "url": "/api/now/table/task_ci",
      "method": "POST",
      "body": {<base64 encode of request body>}
    },
    {
      "id": "13",
      "headers": [
        {
          "name": "Content-Type",
          "value": "application/json"
        }
      ],
      "url": "/api/now/table/task_ci",
      "method": "POST",
      "body": {<base64 encode of request body>}
    }
  ]
}

//body field is NOT base64 encoded
//this format is just to show you the raw data
{
  "batch_request_id": "1",
  "rest_requests": [
    {
      "id": "11",
      "headers": [
        {
          "name": "Content-Type",
          "value": "application/json"
        }
      ],
      "url": "/api/now/table/task_ci",
      "method": "POST",
      "body": {
        "task": "<incident_id>",
        "ci_item": "<ci_1_sys_id>"
      }
    },
    {
      "id": "12",
      "headers": [
        {
          "name": "Content-Type",
          "value": "application/json"
        }
      ],
      "url": "/api/now/table/task_ci",
      "method": "POST",
      "body": {
        "task": "<incident_id>",
        "ci_item": "<ci_2_sys_id>"
      }
    },
    {
      "id": "13",
      "headers": [
        {
          "name": "Content-Type",
          "value": "application/json"
        }
      ],
      "url": "/api/now/table/task_ci",
      "method": "POST",
      "body": {
        "task": "<incident_id>",
        "ci_item": "<ci_3_sys_id>"
      }
    }
  ]
}

A common use case is to have the selected Rootly services for an incident be automtically added to the ServiceNow incident as an Affected CIs.

To support this use case, you must have each ServiceNow CI’s sys_id linked to their equivalent Rootly services.

The following syntax leverages Liquid syntax to dynamically set each the base64 encoded task and ci_item fields in each Table API call:

{
  "batch_request_id": "1",
  "rest_requests": [
{% for service in genius_workflow_run.newly_added_services %}

{% assign task_value = incident.service_now_incident_id %}
{% assign ci_item_value = service | get: 'service_now_ci_sys_id' %}
{% assign body_string = '{ "task": "' | append: task_value | append: '", "ci_item": "' | append: ci_item_value | append: '" }' %}


    {
      "id": "1{{ forloop.index }}",
      "headers": [
        {
          "name": "Content-Type",
          "value": "application/json"
        }
      ],
      "url": "/api/now/table/task_ci",
      "method": "POST",
      "body": "{{ body_string | base64_encode }}"
    }{% unless forloop.last %},{% endunless %}
{% endfor %}
  ]
}

​
Succeed On Status

Set to 200. Unlike most POST requests that returns 201, ServiceNow’s Batch API’s POST endpoint returns 200 status code to signify success.

You don’t need to fill in the rest of the fields in the workflow action. They are more for debugging and notification usage.