> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rootly.com/llms.txt
> Use this file to discover all available pages before exploring further.
# ServiceNow
> Connect ServiceNow to Rootly for bidirectional incident sync, alert ingestion, and CMDB sync into Rootly services, teams, and custom catalogs.
The ServiceNow integration connects Rootly with your ServiceNow instance bidirectionally. Rootly can create and update ServiceNow incidents through workflow actions, ServiceNow can send incident events to Rootly as alerts using Business Rules, and Rootly can sync your ServiceNow CMDB into its catalogs.
With the ServiceNow integration, you can:
* Automatically create ServiceNow incidents from Rootly incidents
* Update ServiceNow incident priority, state, and custom fields as incidents evolve
* Receive ServiceNow incident events as Rootly alerts to trigger on-call paging
* Sync ServiceNow CMDB configuration items into Rootly services, teams, and custom catalogs
## Before You Begin
Before setting up the integration, make sure you have:
* A Rootly account with admin permission to manage integrations
* A ServiceNow instance with admin access
* Permission to create OAuth Application Registry entries in ServiceNow
Rootly recommends installing with a dedicated ServiceNow service account so the integration does not break if an individual user leaves your organization.
## Installation
Log into Rootly as an Admin and navigate to **Configurations > Integrations > ServiceNow**. Click **Setup**.
Log into your ServiceNow instance as an Admin and navigate to **System OAuth > Application Registry**.
Click **New**, then select **Create an OAuth API endpoint for external clients**.
Fill in the following fields and click **Submit**:
| ServiceNow Field | Value |
| - | - |
| `Name` | `Rootly` |
| `Redirect URL` | `https://rootly.com/auth/service_now/callback` |
Open the application you just created in ServiceNow and copy the **Client ID** and **Client Secret**.
When copying the **Client Secret**, you may need to unmask it by clicking the lock icon. Masked values sometimes do not copy correctly in ServiceNow.
Paste the Client ID, Client Secret, and your ServiceNow instance URL into the Rootly setup modal and click **Connect**.
You will be redirected to ServiceNow to authorize the connection. Click **Allow**.
After authorization, the **Create a ServiceNow Incident** and **Update a ServiceNow Incident** workflow actions are available in your Genius workflows.
## Ingest ServiceNow Events
To receive ServiceNow incident events as Rootly alerts, configure a Business Rule in ServiceNow to send events to Rootly's webhook endpoint.
In Rootly, open the ServiceNow integration settings. Copy the **Webhook URL** and **Secret** values shown on the integration page.
In ServiceNow, navigate to **System Definition > Business Rules**.
There are multiple Business Rules pages in ServiceNow. Make sure you select the one under **System Definition**.
Click **New** and fill in:
| Field | Value |
| - | - |
| `Name` | Any descriptive name (for example, `Send to Rootly`) |
| `Table` | `Incident [incident]` |
| `Advanced` | Check this |
| `When` | `After` |
| `Insert` | Check to receive events when incidents are created |
| `Update` | Check to receive events when incidents are updated |
| `Delete` | Check to receive events when incidents are deleted |
Navigate to the **Advanced** tab and replace the script with the following:
```js theme={null}
(function executeRule(current, previous /*null when async*/ ) {
try {
var r = new sn_ws.RESTMessageV2();
r.setEndpoint("");
r.setHttpMethod("post");
r.setRequestHeader("secret", "");
var usr = new GlideRecord('sys_user');
usr.get('sys_id', current.getValue("caller_id"));
var reported_by_email = usr.getValue('email');
var number = current.getValue("number");
var opened_at = current.getValue("opened_at");
var impact = current.getValue("impact");
var urgency = current.getValue("urgency");
var short_description = current.getValue("short_description");
var description = current.getValue("description");
var category = current.getValue("category");
var priority = current.getValue("priority");
var sys_id = current.getValue("sys_id");
var subcategory = current.getValue("subcategory");
var state = current.getValue("state");
var obj = {
"number": number,
"reported_by_email": reported_by_email,
"opened_at": opened_at,
"impact": impact,
"urgency": urgency,
"short_description": short_description,
"description": description,
"category": category,
"priority": priority,
"sys_id": sys_id,
"subcategory": subcategory,
"state": state
};
var body = JSON.stringify(obj);
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);
```
Replace `` and `` with the values from the Rootly ServiceNow integration page.
Click **Submit**.
### How Alerts Are Mapped
Each ServiceNow event received creates a Rootly alert with the following fields:
| Rootly Alert Field | ServiceNow Source |
| - | - |
| Summary | `short_description`, then `description`, then `number` |
| External ID | `sys_id` |
| External URL | `url` (if provided in payload) |
Alert labels:
| Label | ServiceNow Field |
| - | - |
| `id` | `sys_id` |
| `number` | `number` |
| `impact` | `impact` |
| `urgency` | `urgency` |
| `category` | `category` |
| `subcategory` | `subcategory` |
| `state` | `state` |
### Using ServiceNow as an Alert Source
If your org uses Rootly On-Call, ServiceNow alerts can be used to page on-call users. Once the Business Rule is configured, alerts from ServiceNow will appear in your Rootly alert feed and can trigger on-call notifications through alert workflows.
## Workflow Actions
The ServiceNow integration provides workflow actions for creating and updating ServiceNow incidents from Rootly. If you are unfamiliar with how Genius workflows work, visit the [Workflows](/workflows/workflows) documentation first.
### Create a ServiceNow Incident
This action creates a new record in the ServiceNow `Incident` table (for example, `INC0010001`) and links it to the Rootly incident.
| Field | Description | Required |
| - | - | - |
| **Name** | Display name for this workflow action | |
| **Title** | Maps to `short_description` in ServiceNow. Supports Liquid | Yes |
| **Description** | Maps to `description` in ServiceNow. Supports Liquid | |
| **Priority** | Maps to `urgency`. **Auto** mirrors the incident severity | |
| **Status** | Maps to `state`. **Auto** mirrors the incident status | |
| **Acts As User** | Name or email of the ServiceNow user to set as caller when resolving. Only active when status is Resolved (6) | |
| **Custom Fields Mapping** | JSON of additional ServiceNow fields. Merged directly into the incident payload. Supports Liquid | |
**Priority mapping (Auto)**
| Rootly Severity | ServiceNow Urgency |
| - | - |
| Critical | High (1) |
| High | High (1) |
| Medium | Medium (2) |
| Low | Low (3) |
**Status mapping (Auto)**
| Rootly Status | ServiceNow State |
| - | - |
| Started | New (1) |
| Mitigated | In Progress (2) |
| Resolved | Resolved (6) |
Available states: New (1), In Progress (2), On Hold (3), Resolved (6), Closed (7), Canceled (8).
**Acts As User** triggers a ServiceNow user lookup by first name, last name, or email. When matched, Rootly sets `caller_id`, `close_code`, and `close_notes` automatically. It only applies when the state is set to Resolved (6).
### Update a ServiceNow Incident
This action updates an existing record in the ServiceNow `Incident` table.
When a **Create a ServiceNow Incident** action runs, Rootly stores the resulting `sys_id` and incident number on the incident record. Reference them in subsequent update actions using Liquid variables.
| Field | Description | Required |
| - | - | - |
| **Name** | Display name for this workflow action | |
| **Incident ID** | ServiceNow `sys_id` of the incident to update. Supports Liquid | Yes |
| **Title** | Updated `short_description`. Supports Liquid | |
| **Description** | Updated `description`. Supports Liquid | |
| **Priority** | Updated urgency level | |
| **Status** | Updated incident state | |
| **Acts As User** | Name or email of the caller to set when resolving | |
| **Custom Fields Mapping** | Updated custom field values as JSON. Supports Liquid | |
### Common Custom Field Examples
**Work notes (internal)** — visible only to ServiceNow agents, not customers.
```json theme={null}
{
"work_notes": "{{ incident.events[0].event_raw }}"
}
```
**Comments (customer-visible)**
```json theme={null}
{
"comments": "{{ incident.events[0].event_raw }}"
}
```
**Major incident**
```json theme={null}
{
"assignment_group": "3De45d9ebc3b333200fe02c9bb34efc434",
"major_incident_state": "proposed"
}
```
Major incident state changes may require specific ACL permissions in ServiceNow. See the [ServiceNow community](https://community.servicenow.com/community?id=community_question\&sys_id=fae73aeb1b7370900b8a9979b04bcb1a) for details.
### Add Configuration Items (CIs) to an Incident
Adding configuration items to a ServiceNow incident requires multiple API calls (one per CI). Use Rootly's **HTTP Client** workflow action with the ServiceNow Batch API to consolidate them into a single request.
**Endpoint**
```http theme={null}
POST https://.com/api/now/v1/batch
```
**Headers**
```json theme={null}
{
"Accept": "application/json",
"Content-Type": "application/json",
"Authorization": "Basic {{ secrets.service_now_key_encoded }}"
}
```
Store your Base64-encoded `username:password` as a [Rootly Secret](https://rootly.com/account/secrets) to keep credentials out of plain-text workflow configurations.
**Body**
Each individual Table API call must have its `body` Base64-encoded. The following Liquid template dynamically generates one batch entry per service associated with the incident:
```json theme={null}
{
"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 %}
]
}
```
To use this template, each ServiceNow CI's `sys_id` must be linked to the equivalent Rootly service using the `service_now_ci_sys_id` field.
**Succeed On Status** — set to `200`. The ServiceNow Batch API returns `200` (not `201`) on success.
## Sync CMDB Catalogs
Catalog sync makes ServiceNow the source of truth for your Rootly [catalogs](/catalogs). Rootly reads the CMDB classes you select and turns them into Rootly services, teams, and custom catalogs, then keeps them current on a daily schedule.
Catalog sync requires the Rootly Catalog. If the **Sync ServiceNow CMDB catalogs** toggle does not appear in your integration settings, contact Rootly support to enable it for your organization.
### Enable Catalog Sync
Turn on catalog sync from the ServiceNow integration settings and choose the classes to sync.
In Rootly, navigate to **Configurations > Integrations > ServiceNow** and click **Settings**.
Enable **Sync ServiceNow CMDB catalogs**.
Sync CMDB configuration items from ServiceNow to Rootly. While this is on, ServiceNow owns the synced records and their synced properties in Rootly.
Pick one or more classes in **CMDB CI classes**. Rootly lists the classes it can read from your instance, plus the group classes described below. At least one class is required.
The ServiceNow tables to sync. Each class maps to a Rootly service, team, or custom catalog according to the [class mapping](#how-classes-map-to-rootly).
Click **Save**. Rootly starts the first sync immediately and shows a **Syncing ServiceNow CMDB** progress modal. When it completes, Rootly redirects you to the catalogs page.
Synced services, teams, catalogs, and entities show a **Synced from ServiceNow** badge. The badge links back to the integration settings.
Rootly also starts a sync whenever you change the selected classes. After that, it syncs every 24 hours. The integration settings show when the last sync finished.
### How Classes Map to Rootly
Each selected class syncs into a different Rootly resource.
| ServiceNow class | Rootly resource |
| - | - |
| **Service** (`cmdb_ci_service`) and **Business Application** (`cmdb_ci_business_app`) | Services. The CI's support group becomes the owning team. |
| **Group** (`sys_user_group`) and **Group (CMDB CI)** (`cmdb_ci_group`) | Teams. The group's name and description sync to the team. |
| **Group Members** (`sys_user_grmember`) | Team members. Select this class to also sync the members of synced groups. Each ServiceNow member is matched by email to a user in your Rootly organization. |
| Any other CMDB CI class | A custom catalog named after the class label, with one entity per CI. The support group on each CI also syncs to a team. |
Only operational CIs sync, in other words, CIs whose `operational_status` is `Operational`. For **Group**, only active groups sync.
For every synced service, team, and entity, Rootly sets the name and description from the ServiceNow record and adds these properties, marked as managed by ServiceNow. Rootly adds a property only when the record has a value for it.
| Property | ServiceNow source | Applies to |
| - | - | - |
| **Description** | `short_description`, then `description` | All classes |
| **Support Group** | `support_group`, as a link to the synced team | CMDB CI classes |
| **Operational Status** | `operational_status` | CMDB CI classes |
| **ServiceNow URL** | A link to the record in your ServiceNow instance | All classes |
Teams from **Group** (`sys_user_group`) receive only **Description** and **ServiceNow URL**, because that table has no support group or operational status. **Group Members** adds no properties. It only manages team membership.
#### Matching Existing Records
Rootly keys each synced record on the ServiceNow `sys_id`, so renames in ServiceNow update the same Rootly record. When a CI has no linked record yet, Rootly adopts an existing unlinked service, team, catalog, or entity with the same name before creating a new one. If a name is already taken by a different record, Rootly appends a numeric suffix, for example `Payments (2)`.
Services imported by an earlier CMDB-to-services sync keep their ServiceNow link, so enabling catalog sync updates them in place.
#### Removals and Cleanup
After a sync completes with no errors, Rootly cleans up records for CIs that ServiceNow no longer returns, because the CI was deleted or is no longer operational:
* Records that catalog sync created are removed.
* Records that catalog sync adopted are unlinked from ServiceNow and kept as regular Rootly records.
A sync that records any error skips cleanup for that run, so a transient failure never removes records.
Deselecting a class in **CMDB CI classes** stops syncing it. Custom catalogs and their entities from that class stay in Rootly and become editable. Teams that no longer come from any selected class are removed or unlinked on the next completed sync, as are services when the other service class is still selected.
Removing a CI in ServiceNow, or changing its operational status, removes the matching record from Rootly on the next completed sync if catalog sync created it. Rootly cannot restore a removed record. Records that existed before the sync adopted them are unlinked instead.
#### Team Members
When **Group Members** is selected, Rootly adds and removes team members to match ServiceNow group membership. Rootly matches each member's email in ServiceNow to any user in your Rootly organization. Rootly only manages the members it added: members you add manually stay on the team. A member whose email does not match a Rootly user appears on the sync errors page, and the rest of the group still syncs. If Rootly cannot read group membership from ServiceNow, it leaves existing members untouched.
Deselect **Group Members** to stop managing members. Existing members stay on their teams.
### Protected Records
While catalog sync is on, Rootly protects what ServiceNow owns:
* Synced services, teams, catalogs, and entities cannot be deleted in Rootly.
* Properties managed by ServiceNow cannot be edited in Rootly. Add your own properties to a synced catalog and edit them as usual.
* Owner teams that the sync assigned to a service follow the CI's support group. Owner teams you add manually stay.
Rootly shows a tooltip explaining why a control is disabled. Turning off catalog sync lifts the protection and keeps the records.
### Run a Sync Manually
Use **Sync now** in the integration settings to sync without waiting for the daily schedule. Rootly first checks the catalogs it is about to write into.
In the ServiceNow integration settings, click **Sync now**.
If a target catalog has a required property that ServiceNow does not populate, Rootly shows the **Required properties detected** modal. For each class, choose one option:
Rootly marks the listed properties as optional and syncs the class. You need permission to edit catalog properties.
Rootly removes the class from **CMDB CI classes** and syncs the remaining classes.
Click **Confirm and sync**. If every class is skipped, nothing syncs.
The **Syncing ServiceNow CMDB** modal shows the percentage complete. When the sync finishes, Rootly redirects to the catalogs page. If the sync recorded errors, Rootly redirects to the sync errors page instead.
### Sync Errors
A problem with one CI does not stop the sync. Rootly records the failure and continues with the next record. When a sync has errors, the integration settings show a **View sync errors** button, and the **Synced from ServiceNow** badge shows a warning icon.
The **ServiceNow Sync Errors** page lists each error with the entity, its class, the operation that failed, the error message, and when it occurred. Search the list to find a specific record, and click **Sync again** after fixing the cause. Each new full sync clears the previous errors.
### Troubleshooting
Catalog sync requires the Rootly Catalog and must be enabled for your organization. Contact Rootly support to turn it on.
For CMDB CI classes, Rootly only syncs CIs whose `operational_status` is `Operational`. For **Group**, Rootly only syncs active groups. Check the status of the records in ServiceNow. Also confirm the OAuth application's user has read access to the table. A table Rootly cannot read appears on the sync errors page.
Members sync only when **Group Members** is selected in **CMDB CI classes**, and only for teams that came from **Group** or **Group (CMDB CI)** in the same sync. Each member's email in ServiceNow must match a user in your Rootly organization. Unmatched emails appear on the sync errors page.
A failed sync usually means Rootly could not authenticate to ServiceNow, for example an expired OAuth token that could not be refreshed. Rootly does not remove any records when a sync fails. Reconnect the integration if needed, then click **Sync now**.
## Uninstall
To remove the ServiceNow integration, navigate to **Configurations > Integrations > ServiceNow > Delete**.
Removing the integration stops catalog sync. Records synced from ServiceNow stay in Rootly as regular records and no longer update.
## Related Resources
* [Catalogs](/catalogs)
* [Workflows](/workflows/workflows)
* [Alert workflows](/workflows/alert-workflows)
* [Integrations overview](/integrations/overview)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.