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

1. In Datadog, go to the ServiceNow integration settings page.

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

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

4. 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.

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

6. 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.

action

Type: String
The action being taken on the monitor: create, update, acknowledge, or resolve

additional_information

Type: String
ITOM Transform: additional_info
Formatted string containing all event details

aggreg_key

Type: String
Aggregation key representing a hash of the alerting monitor’s ID

alert_cycle_key

Type: String
Key representing a hash of a single monitor’s alert cycle (tracks Alert → Warn → Resolve)

alert_id

Type: String
ID of the alerting monitor

alert_metric

Type: String
ITOM Transform: metric_name
Metric that triggered the alert

alert_query

Type: String
Query that triggered the alert

alert_scope

Type: String
Scope that triggered the alert

alert_status

Type: String
Current state of the alert

alert_title

Type: String
Name of the alert

alert_transition

Type: String
ITSM Transform: (script) -> state
Alert transition state: Triggered, Warn, or Recovered

assignment_group_sys_id

Type: Reference
ITSM Transform: assignment_group
Reference Table: Group
ServiceNow sys_id for the templated handle’s assignment group

business_service_sys_id

Type: Reference
ITSM Transform: business_service
Reference Table: Service
ServiceNow sys_id for the templated handle’s business service

custom_fields

Type: String
User-configured key-value fields formatted as JSON-convertible string

datadog_tags

Type: String
Datadog tags from the alerting monitor

description

Type: String
ITSM Transform: description
ITOM Transform: description
Summary description of the monitor alert

event_details

Type: String
ITSM Transform: work_notes
Event details with formatted, clickable links to Datadog

event_id

Type: String
Datadog ID of the event

event_link

Type: String
Link to the event created from the monitor alert

event_msg

Type: String
Message from the event

event_title

Type: String
ITSM Transform: short_description
Title of the event

event_type

Type: String
ITOM Transform: type
Type of event

hostname

Type: String
ITSM Transform: cmdb_ci
ITOM Transform: node
Host of the affected monitor

impact

Type: Integer
ITSM Transform: impact
Impact value based on user-defined mapping of monitor priority

logs_sample

Type: String
Sample of relevant logs

monitor_priority

Type: Integer
ITOM Transform: severity
Priority of the alerting monitor as an integer

org_name

Type: String
Name of the alerting monitor’s organization

sys_created_by

Type: String
ITSM Transform: caller_id
Creator of the record (usually the configured ServiceNow API account)

ticket_state

Type: String
ITSM Transform: state, (script) -> close_code, (script) -> close_notes
ITOM Transform: (script) -> resolution_notes
State of the ServiceNow record: new or resolved

u_correlation_id

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

urgency

Type: Integer
ITSM Transform: urgency
Urgency set from the user defined mapping on the integration tile based on monitor defined priority

user_sys_id

Type: Reference
ITSM Transform: assigned_to
Reference Table: User
sys_id from the templated handle passed in for user.

This section describes the fields that are synced between Incident Management and ServiceNow:

Note: If Start at SEV-0 is enabled in Incident Management settings, the values in ServiceNow Urgency, ServiceNow Impact, and ServiceNow Priority will all stay the same, but the Datadog Incident Severity shifts down by 1. For example, in the first row of this table, the Datadog Incident Severity would be 0, but the rest of the values in the rest of the row would stay the same.

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.

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.

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

   At the top are two important fields on the Transform record: Source table and Target table:

3. Click New:

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

   Or check the Use source script box and define transformations:

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:

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.

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.

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.

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.

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 by grouping it using a tag in the metric. This way, each alert will trigger a separate incident.