---
title: Set up ServiceNow ITOM and ITSM
description: Datadog, the leading service for cloud-scale monitoring.
breadcrumbs: Docs > Integrations > Integration Guides > Set up ServiceNow ITOM and ITSM
---

# Set up ServiceNow ITOM and ITSM

ServiceNow's ITOM/ITSM integration allows you to send alerts, cases, and incidents generated in Datadog to ServiceNow as records in the Incident or Event tables. The integration relies on interim tables and transform maps.

To use the integration, follow the instructions to install it, and then configure it for each product:

1. Configure the ServiceNow tile
1. Install the ITOM/ITSM integration
1. Configure the integration
   1. Configure Datadog templated monitor notifications
   1. Configure Datadog Case Management
   1. Configure Datadog Incident Management
1. Customize data with transform maps

## Configure the ServiceNow tile{% #tile %}

Before installing the integration, ensure you have the [ServiceNow tile configured](https://docs.datadoghq.com/integrations/servicenow/#configure-the-servicenow-tile-in-datadog) with your ServiceNow instance in Datadog.

## Install the ITOM/ITSM integration{% #install %}

There are two ways to install the integration:

- Datadog recommends installing the latest version of the [ITOM/ITSM Integration for Datadog](https://store.servicenow.com/store/app/e0e963a21b246a50a85b16db234bcb67) integration from the ServiceNow store.
- Alternatively, you can download the latest Update Set (Datadog-Snow_Update_Set_v2.7.9.xml) and upload it to your ServiceNow instance manually.

## Configure the integration{% #configure-the-integration %}

### Configure templated monitor notifications{% #monitor-notifications %}

{% alert level="info" %}
These features require ITOM/ITSM integration version 2.6.0 or newer.
{% /alert %}

#### Configure instance priority mapping{% #configure-instance-priority-mapping %}

By default, Datadog doesn't include ServiceNow impact and urgency levels when sending events to ServiceNow. For each ServiceNow configuration, you can configure mappings between those ServiceNow levels and Datadog's Monitor Priority levels for inclusion in Datadog-generated events.

1. In Datadog, go to the [ServiceNow integration settings](https://app.datadoghq.com/integrations?integrationId=servicenow) page.
1. Go to the **Configure** tab, then the **ITOM/ITSM** tab, then the **Monitors** tab.
1. Under **Instance Priority Mapping for Templates**, open the settings for your ServiceNow instance.
1. Turn on the **Use Instance Priority Mapping** toggle.
1. Under **ServiceNow Urgency** and **ServiceNow Impact**, select the levels you want to correspond with Datadog's Monitor Priority levels. For example:
   - Impact: 4
   - Urgency: 5
1. Click **Update**.

#### Create a custom ServiceNow @-handle for monitor notifications{% #create-a-custom-servicenow--handle-for-monitor-notifications %}

To create a ServiceNow record from a monitor, you need to configure an @-handle to use within the monitor notification rules or notification recipients.

1. In Datadog, go to the [ServiceNow integration settings](https://app.datadoghq.com/integrations?integrationId=servicenow) page.
1. Go to the **Configure** tab, then the **ITOM/ITSM** tab, then the **Monitors** tab.
1. Beside **Templates**, click **+ New** to create a new template.
1. Define an @-handle **Name**, **Instance**, and **Target Table** for the monitor notification to be delivered to.
1. (Optional) Set **Assignment Group**, **Business Service**, and/or **User** in the template.**Note**: If you set both an assignment group and user, the user must belong to the selected assignment group for the ServiceNow record creation to successfully complete.
1. (Optional) Expand the **Customize notification payload** section and click **Add field** to add more variables from Datadog.
1. Click **Save**.

To use the new template, add `@servicenow-<TEMPLATE_NAME>` in a monitor description. When the monitor alerts, ServiceNow also creates a corresponding record, and automatically sets it to **Resolved** when the underlying alert recovers.

{% collapsible-section #configure-legacy-monitor-notifications %}
#### Configure legacy monitor notifications

To configure legacy monitor notifications using `@servicenow-<INSTANCE_NAME>`:

1. In Datadog, go to the [ServiceNow integration settings](https://app.datadoghq.com/integrations?integrationId=servicenow) page.

1. Go to the **Configure** tab, then the **ITOM/ITSM** tab, then the **Monitors** tab.

1. Under **Manage Legacy Monitor Notifications**, select the instance you want to configure notifications for, then select the table that legacy monitor notifications write to.

1. To validate the integration is set up correctly, add `@servicenow-<INSTANCE_NAME>` in a monitor or event notification. You can define both the `Impact` and `Urgency` values so ServiceNow can use them to calculate the incident priority. The raw data populates rows in the interim table and is forwarded to the ServiceNow table specified by the integration.

   {% image
      source="https://datadog-docs.imgix.net/images/integrations/guide/servicenow/servicenow-priority-field-mapping.cf663077dd7a4d6b05b0a0d217ad8c70.png?auto=format"
      alt="Example legacy monitor with defined Impact and Urgency values" /%}

1. Use transform maps in ServiceNow to customize the transformation of the data sent to the interim tables.

1. Customize the notification payload with available Datadog variables or custom strings.

**Note**: `Impact` and `Urgency` in monitor descriptions work only for legacy monitor configurations. For templated monitors, configure instance priority mapping. The `priority` field in ServiceNow incidents is read-only, and can only be updated using [priority lookup rules](https://docs.servicenow.com/en-US/bundle/sandiego-it-service-management/page/product/incident-management/task/def-prio-lookup-rules.html).
{% /collapsible-section %}

{% collapsible-section #templated-monitor-table-fields-transform-maps %}
#### Templated monitor table fields and transform maps

{% dl %}

{% dt %}
`action`
{% /dt %}

{% dd %}
**Type**: StringThe action being taken on the monitor: `create`, `update`, `acknowledge`, or `resolve`
{% /dd %}

{% dt %}
`additional_information`
{% /dt %}

{% dd %}
**Type**: String**ITOM Transform**: `additional_info`Formatted string containing all event details
{% /dd %}

{% dt %}
`aggreg_key`
{% /dt %}

{% dd %}
**Type**: StringAggregation key representing a hash of the alerting monitor's ID
{% /dd %}

{% dt %}
`alert_cycle_key`
{% /dt %}

{% dd %}
**Type**: StringKey representing a hash of a single monitor's alert cycle (tracks Alert → Warn → Resolve)
{% /dd %}

{% dt %}
`alert_id`
{% /dt %}

{% dd %}
**Type**: StringID of the alerting monitor
{% /dd %}

{% dt %}
`alert_metric`
{% /dt %}

{% dd %}
**Type**: String**ITOM Transform**: `metric_name`Metric that triggered the alert
{% /dd %}

{% dt %}
`alert_query`
{% /dt %}

{% dd %}
**Type**: StringQuery that triggered the alert
{% /dd %}

{% dt %}
`alert_scope`
{% /dt %}

{% dd %}
**Type**: StringScope that triggered the alert
{% /dd %}

{% dt %}
`alert_status`
{% /dt %}

{% dd %}
**Type**: StringCurrent state of the alert
{% /dd %}

{% dt %}
`alert_title`
{% /dt %}

{% dd %}
**Type**: StringName of the alert
{% /dd %}

{% dt %}
`alert_transition`
{% /dt %}

{% dd %}
**Type**: String**ITSM Transform**: (script) -> stateAlert transition state: `Triggered`, `Warn`, or `Recovered`
{% /dd %}

{% dt %}
`assignment_group_sys_id`
{% /dt %}

{% dd %}
**Type**: Reference**ITSM Transform**: `assignment_group`**Reference Table**: GroupServiceNow sys_id for the templated handle's assignment group
{% /dd %}

{% dt %}
`business_service_sys_id`
{% /dt %}

{% dd %}
**Type**: Reference**ITSM Transform**: `business_service`**Reference Table**: ServiceServiceNow sys_id for the templated handle's business service
{% /dd %}

{% dt %}
`custom_fields`
{% /dt %}

{% dd %}
**Type**: StringUser-configured key-value fields formatted as JSON-convertible string
{% /dd %}

{% dt %}
`datadog_tags`
{% /dt %}

{% dd %}
**Type**: StringDatadog tags from the alerting monitor
{% /dd %}

{% dt %}
`description`
{% /dt %}

{% dd %}
**Type**: String**ITSM Transform**: `description`**ITOM Transform**: `description`Summary description of the monitor alert
{% /dd %}

{% dt %}
`event_details`
{% /dt %}

{% dd %}
**Type**: String**ITSM Transform**: `work_notes`Event details with formatted, clickable links to Datadog
{% /dd %}

{% dt %}
`event_id`
{% /dt %}

{% dd %}
**Type**: StringDatadog ID of the event
{% /dd %}

{% dt %}
`event_link`
{% /dt %}

{% dd %}
**Type**: StringLink to the event created from the monitor alert
{% /dd %}

{% dt %}
`event_msg`
{% /dt %}

{% dd %}
**Type**: StringMessage from the event
{% /dd %}

{% dt %}
`event_title`
{% /dt %}

{% dd %}
**Type**: String**ITSM Transform**: `short_description`Title of the event
{% /dd %}

{% dt %}
`event_type`
{% /dt %}

{% dd %}
**Type**: String**ITOM Transform**: `type`Type of event
{% /dd %}

{% dt %}
`hostname`
{% /dt %}

{% dd %}
**Type**: String**ITSM Transform**: `cmdb_ci`**ITOM Transform**: `node`Host of the affected monitor
{% /dd %}

{% dt %}
`impact`
{% /dt %}

{% dd %}
**Type**: Integer**ITSM Transform**: `impact`Impact value based on user-defined mapping of monitor priority
{% /dd %}

{% dt %}
`logs_sample`
{% /dt %}

{% dd %}
**Type**: StringSample of relevant logs
{% /dd %}

{% dt %}
`monitor_priority`
{% /dt %}

{% dd %}
**Type**: Integer**ITOM Transform**: `severity`Priority of the alerting monitor as an integer
{% /dd %}

{% dt %}
`org_name`
{% /dt %}

{% dd %}
**Type**: StringName of the alerting monitor's organization
{% /dd %}

{% dt %}
`sys_created_by`
{% /dt %}

{% dd %}
**Type**: String**ITSM Transform**: `caller_id`Creator of the record (usually the configured ServiceNow API account)
{% /dd %}

{% dt %}
`ticket_state`
{% /dt %}

{% dd %}
**Type**: String**ITSM Transform**: `state`, (script) -> close_code, (script) -> close_notes**ITOM Transform**: (script) -> resolution_notesState of the ServiceNow record: `new` or `resolved`
{% /dd %}

{% dt %}
`u_correlation_id`
{% /dt %}

{% dd %}
**Type**: String**ITSM Transform**: `correlation_id`**ITOM Transform**: `message_key`Combined alert_cycle_key and aggreg_key used to coalesce records to the same target incident
{% /dd %}

{% dt %}
`urgency`
{% /dt %}

{% dd %}
**Type**: Integer**ITSM Transform**: `urgency`Urgency set from the user defined mapping on the integration tile based on monitor defined priority
{% /dd %}

{% dt %}
`user_sys_id`
{% /dt %}

{% dd %}
**Type**: Reference**ITSM Transform**: `assigned_to`**Reference Table**: Usersys_id from the templated handle passed in for user.
{% /dd %}

{% /dl %}

{% /collapsible-section %}

### Configure Datadog Case Management{% #case-management %}

{% callout %}
# Important note for users on the following Datadog sites: app.ddog-gov.com



{% alert level="warning" %}
Case Management integration is not supported in the  site.
{% /alert %}


{% /callout %}

Send cases from Datadog to either the Datadog Cases ITOM or ITSM table in ServiceNow. ServiceNow stores incoming records and uses the installed update set to transform the records in the Event or Incident table. Datadog doesn't support custom payloads for these tables, or updates to the Events table.

{% alert level="info" %}
The user configuring the settings in ServiceNow must have both the `x_datad_datadog.user` and `admin` roles.
{% /alert %}

1. In Datadog, go to the [ServiceNow integration settings](https://app.datadoghq.com/integrations?integrationId=servicenow) page.
1. Go to the **Configure** tab, then the **ITOM/ITSM** tab, then the **Case Management** tab.
1. Under **Sync ServiceNow with Case Management**, open the settings for your ServiceNow instance.
1. Beside **Case Table**, choose to send cases to either **Datadog Cases ITOM** or **Datadog Cases ITSM**.
1. Navigate to the [**Case Management > Settings**](https://app.datadoghq.com/cases/settings) page, and expand your project. Then, [set up the ServiceNow integration](https://docs.datadoghq.com/incident_response/case_management/notifications_integrations/#servicenow) for that project.

### Configure Datadog Incident Management{% #incident-management %}

The Datadog ServiceNow integration allows you to create incidents in ServiceNow from Datadog incidents and sync data bidirectionally between the two platforms. This integration with Datadog Incident Management provides improved visibility, automatic bidirectional sync of the incident's state, severity, and any status updates, and support for your existing ServiceNow workflows.

After installing the integration, in Datadog, go to the [Integration Settings](https://app.datadoghq.com/incidents/settings?section=integrations) page. Click the **ServiceNow** tile to configure ServiceNow incident creation.

For step-by-step instructions on setting up and configuring this integration for incident management, see [Integrate ServiceNow with Datadog Incident Management](https://docs.datadoghq.com/incident_response/incident_management/integrations/servicenow).

## Sync data bidirectionally between ServiceNow and Case/Incident Management{% #sync-bidirectionally %}

In ServiceNow, you can sync state, impact, and urgency bidirectionally with both Case Management and Incident Management.

**Note**: Data only syncs from ServiceNow back to Datadog if the change is made by a user with the ITIL role who is **not** the user configured in the ServiceNow integration tile in Datadog.

1. In Datadog, follow the instructions to [create a service account application key](https://docs.datadoghq.com/account_management/org_settings/service_accounts/#create-or-revoke-application-keys).**Note**: Datadog recommends creating this key instead of using a personal one, which risks breaking the ServiceNow sync if the user's account is deactivated or if their permissions change.
1. In ServiceNow, click the globe icon in the top-right corner, then make sure the **Application Scope** is set to **ITOM/ITSM Integration for Datadog**.
1. In the top-left navigation menu, click **All**.
1. Type **ITOM/ITSM Integration for Datadog** in the filter.
1. Click the **Configuration** link from the filtered results, then enter the required settings:
   1. Select your **Datadog Data Center**.
   1. Paste in your **Datadog API Key**.
   1. Paste in your **Service Account Application Key** you created.
   1. Check the **Enabled** box.
1. Click **Save**.
1. (Optional) If you have ITOM/ITSM integration version 2.7.0 or newer, you can use information from correlated alerts to populate values in ServiceNow.Instructions on how to do so can be found below under **Transform correlated alert data**.

## Customize data with transform maps{% #transform-maps %}

The ServiceNow integration writes from Datadog to interim tables, which transform to records in ServiceNow. For any customizations (for example, custom field mappings), you can extend the transform maps to specify what fields you want to map to from Datadog to ServiceNow.

## Additional configuration options{% #additional-configuration-options %}

{% collapsible-section #import-host-auto-flush %}
#### Datadog import host auto-flush rule

To prevent the import set table `x_datad_datadog_import_host` from accumulating too many rows, an auto-flush rule has been added to the Table Cleaner tool to keep only the last 24 hours of data. This configuration setting can be changed as needed by navigating to `sys_auto_flush_list.do` in the filter navigator and going into the rule for the `x_datad_datadog_import_host` table. The `Age in seconds` field can be updated accordingly.
{% /collapsible-section %}

{% collapsible-section #custom-field-mappings %}
#### Create custom field mappings in ServiceNow

To create a custom field mapping in ServiceNow:

1. Click one of the tables (for example, **Datadog Monitors ITSM Tables**), and scroll to the bottom of the record to see the link for the associated transform map.

1. Click on the name of the transform map to view the record:

   {% image
      source="https://datadog-docs.imgix.net/images/integrations/guide/servicenow/servicenow-click-transform-map.7fc9e005a0188c33277a52c01f7d3330.png?auto=format"
      alt="ServiceNow Table Transform Map showing the Datadog Incident Transform that maps the Datadog Incident Table to the Incident table." /%}
At the top are two important fields on the Transform record: `Source table` and `Target table`:
   {% image
      source="https://datadog-docs.imgix.net/images/integrations/guide/servicenow/servicenow-source-target-fields.9f3d242c6017f962068ce4d2b69993af.png?auto=format"
      alt="Datadog Incident Transform map in ServiceNow showing the source table Datadog Incident Table mapped to the target table Incident [incident]" /%}

1. Click **New**:

   {% image
      source="https://datadog-docs.imgix.net/images/integrations/guide/servicenow/servicenow-click-new.431ade6f9988a46c52dd921c8f011f01.png?auto=format"
      alt="Field Maps tab in ServiceNow showing source and target field mappings for the Datadog Incident Transform. A pink arrow points to the New button used to add a new field map." /%}

1. Select the source and target fields for one to one mappings:

   {% image
      source="https://datadog-docs.imgix.net/images/integrations/guide/servicenow/servicenow-select-source-target.d7b70087bb9bf6904179d892079143ac.png?auto=format"
      alt="ServiceNow Field Map configuration showing the source field PRIORITY mapped to the target field Severity in the Datadog Incident Transform map" /%}
Or check the **Use source script** box and define transformations:
   {% image
      source="https://datadog-docs.imgix.net/images/integrations/guide/servicenow/servicenow-script-example.16e2853d9a16c7fe9f50f5f229b68fd1.png?auto=format"
      alt="ServiceNow Field Map script in the Datadog Incident Transform showing a source script that maps source.priority values to numerical severity levels for the Priority field in the Incident table." /%}

To map custom fields in the integration tile, you can use the following script for either the Datadog Monitors ITOM and Datadog Monitors ITSM Transform maps. In this example, the field `my_field` is defined as a custom field in the integration tile:

```gdscript3
answer = (function transformEntry(source)
{
    var additional_info = JSON.parse(source.additional_info);
    return additional_info.my_field;
})(source);
```

**Notes**:

- The source is the import set table you selected (in this example, Datadog Monitors ITSM Tables) and the target is your actual incident table (or event table) where events are stored.

- The field mappings are at the bottom of the record. Some basic mappings are included. This is where you select the fields to include, define the format, and select the target fields in your ServiceNow instance.

{% /collapsible-section %}

{% collapsible-section #transform-correlated-alert-data %}
#### Transform correlated alert data

To use information from correlated alerts to populate values in ServiceNow, add a new onBefore transform script under the Datadog Cases ITSM/ITOM table transform map.

To populate data into the ServiceNow incident, you have to modify your script to parse data that has been sent from Datadog and stored in the EM Correlated Alert column, and specify which fields in the incident you want to send the parsed data to. Below is a sample script that you can customize for your needs:

```gdscript3
(function runTransformScript(source, map, log, target /*undefined onStart*/ ) {
    // We do not need to process non-correlated-alert events
    if (!source.em_correlated_alert_id) {
        return;
    }

    // Create a GlideRecord for the table
    var gr = new GlideRecord('x_datad_datadog_case_incident_table');
    gr.addQuery('case_id', source.case_id);
    gr.addNotNullQuery('em_correlated_alert_id');
    gr.orderByDesc('sys_created_on');
    gr.query();

    // Ensure we process each alert_id only once
    var seenAlert = {};

    // Add relevant correlated alert fields here
    var alertNames = [];


    // Loop through list of correlated_alerts associated with the same case_id
    while (gr.next()) {
        var emAlertId = gr.getValue('em_correlated_alert_id');

        if (!seenAlert.hasOwnProperty(emAlertId)) {
            seenAlert[emAlertId] = true;
            var changeType = gr.getValue('em_change_type');
            if (changeType == "added") {
                var correlatedAlert = gr.getValue("em_correlated_alert");
                var jsonAlert = JSON.parse(correlatedAlert);

                // Get relevant fields from the JSON event
                var alertName = jsonAlert['alert_message'];
                alertNames.push(alertName);
            }
        }
    }

    // Set the corresponding value on the incident table
    // target.impact = 1;

})(source, map, log, target);
```

{% /collapsible-section %}

## Troubleshooting{% #troubleshooting %}

{% collapsible-section #troubleshooting-error-messages %}
#### Error message in your Datadog integration

If you get an error message in your Datadog integration tile, or an `Error while trying to post to your ServiceNow instance` notification:

- Verify only the subdomain was used when entering your instance name.

- Verify the user you created has the required permissions.

- Verify the username and password are correct.

{% /collapsible-section %}

{% collapsible-section #troubleshooting-no-ticket %}
#### No ticket created

If the integration is configured and an alert triggered, but no ticket is created:

- Confirm that the interim table is populated. If so, the issue is with mappings and transformations. You can debug your mappings and scripts further by navigating to **Transform Errors** in ServiceNow.
- Confirm that you're working with the interim table you specified in the tile.

The ServiceNow user needs `rest_service` and `x_datad_datadog.user` roles so that it can access the import tables. If you're using the legacy way of sending notifications directly to either the Incident table or Event table, you need the permissions `itil` and `evt_mgmt_integration`.
{% /collapsible-section %}

{% collapsible-section #troubleshooting-no-updates %}
#### No updates from ServiceNow to Datadog

If you're seeing updates from Datadog Case Management to ServiceNow, but not seeing updates from ServiceNow to Datadog, this is expected behavior for ServiceNow ITOM. Bidirectional syncing with Case Management is only supported for ServiceNow ITSM.
{% /collapsible-section %}

{% collapsible-section #troubleshooting-monitors-duplicating-incidents %}
#### Monitors duplicating incidents

If a monitor is reopening the same incident instead of creating a new one for each warning, ensure it is not set as a simple alert. Convert the monitor to a [multi-alert](https://docs.datadoghq.com/monitors/configuration/?tab=thresholdalert#multi-alert) by grouping it using a tag in the metric. This way, each alert will trigger a separate incident.
{% /collapsible-section %}

Need additional help? Contact [Datadog support](https://docs.datadoghq.com/help/).

## Further reading{% #further-reading %}

- [ServiceNow integration](https://docs.datadoghq.com/integrations/servicenow/)