ServiceNow CMDB Integration Setup Guide

The ServiceNow CMDB integration automatically syncs Configuration Item (CI) data from your ServiceNow instance to PagerDuty's Enrichment Service. This creates enrichment data tables that enable you to enrich incoming PagerDuty events with contextual information from your ServiceNow CMDB. Read more about event enrichment in the Event Enrichment documentation.

How It Works

1. Configure CMDB Tables — Define which ServiceNow CMDB tables to sync (for example, cmdb_ci_server, cmdb_ci_ip_switch).
2. Map Fields — Specify which ServiceNow fields to use for matching events and which fields provide enrichment data.
3. Sync Data — Enable synchronization to automatically keep enrichment data up-to-date.
4. Enrich Events — Use the synced data in Event Enrichment rules to add context to alerts.

Each CMDB table configuration creates a corresponding enrichment schema that acts as a queryable data table for event enrichment.

Step 1: Create ServiceNow Integration

Create your integration with at least one CMDB table configuration. Credentials are added separately in Step 2.

Request

curl -X POST "https://api.pagerduty.com/enrichment/integrations/servicenow" \
  -H "Authorization: Token token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production CMDB Integration",
    "description": "Enrichment data from production ServiceNow instance",
    "cmdb_tables": [
      {
        "display_name": "Network Switches",
        "ci_table_name": "cmdb_ci_ip_switch",
        "query_filter": "operational_status=1",
        "field_mappings": [
          {
            "servicenow_field": "name",
            "event_field": "source"
          },
          {
            "servicenow_field": "operational_status",
            "event_field": "Operational Status"
          },
          {
            "servicenow_field": "support_group",
            "event_field": "Support Group"
          },
          {
            "servicenow_field": "u_platform",
            "event_field": "Platform"
          },
          {
            "servicenow_field": "sys_class_name",
            "event_field": "CI Class"
          }
        ]
      }
    ]
  }'

Response: 201 Created

{
  "integration": {
    "id": "AGOACUG45VYBRJ6ZCGTBQFN5S4",
    "name": "Production CMDB Integration",
    "description": "Enrichment data from production ServiceNow instance",
    "cmdb_tables": [
      {
        "id": "AGOACUG5DR2ETBH5HBXUPP7KVI",
        "display_name": "Network Switches",
        "ci_table_name": "cmdb_ci_ip_switch",
        "query_filter": "operational_status=1",
        "field_mappings": [
          {
            "servicenow_field": "name",
            "event_field": "source"
          },
          {
            "servicenow_field": "operational_status",
            "event_field": "Operational Status"
          },
          {
            "servicenow_field": "support_group",
            "event_field": "Support Group"
          },
          {
            "servicenow_field": "u_platform",
            "event_field": "Platform"
          },
          {
            "servicenow_field": "sys_class_name",
            "event_field": "CI Class"
          }
        ],
        "status": "disabled",
        "created_at": "2026-01-27T21:16:43Z",
        "updated_at": "2026-01-27T21:16:43Z",
        "deleted_at": null
      }
    ],
    "credentials": null,
    "created_at": "2026-01-27T21:16:43Z",
    "updated_at": "2026-01-27T21:16:43Z"
  }
}

Understanding Table Status

Each CMDB table has a status field indicating the current state of data synchronization:

• disabled: Data sync is not enabled (default for newly created tables).
• syncing: Initial sync in progress, data is being loaded from ServiceNow.
• active: Sync is healthy and incremental updates are running.
• error: Sync failed with an error (check credentials or table configuration).

Tables are created with status: "disabled" by default. You must explicitly enable sync (see Step 6) to begin data synchronization.

Understanding Field Mappings

Field mappings define how ServiceNow CMDB data maps to PagerDuty event fields:

• servicenow_field: The column name in your ServiceNow CMDB table.
• event_field: The field name that appears in enriched PagerDuty events.

At least one field mapping is required. Typically, you map one ServiceNow field (like name or sys_id) to a query field in your events (like source or host), and additional ServiceNow fields to provide enrichment context.

Query Filters

The optional query_filter parameter allows you to limit which CIs are synced from ServiceNow using ServiceNow's query syntax:

Examples

Syncs only CIs with operational status = 1 (operational):

operational_status=1

Syncs only CIs where the custom field u_deployment_status is not null:

u_deployment_status!=NULL

Syncs CIs belonging to "Database Team" and with category "Production" (use ^ for AND conditions):

support_group=Database Team^category=Production

Dot-Walked Fields

ServiceNow allows you to traverse relationships using dot-walking syntax. This is useful when the enrichment data you need is in a related table.

Examples

This dot-walks from the CI to its support group, then to the group's manager, and finally retrieves the manager's email address.

{
  "servicenow_field": "support_group.manager.email",
  "event_field": "Support Manager Email"
}

Common Dot-Walk Patterns

• support_group.name — Get the support group's display name.
• location.city — Get the CI's location city.
• assigned_to.email — Get the assigned user's email address.

Step 2: Add ServiceNow Credentials

Add authentication credentials for your ServiceNow instance.

curl -X POST "https://api.pagerduty.com/enrichment/integrations/servicenow/credentials" \
  -H "Authorization: Token token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": {
      "instance_endpoint": "https://your-instance.service-now.com",
      "user": "integration_user",
      "password": "YOUR_SERVICENOW_PASSWORD"
    }
  }'

Response: 201 Created

{
  "credentials": {
    "id": "AGOCLRSKSB5OPMBBNIQC5X5R6E",
    "instance_endpoint": "https://your-instance.service-now.com",
    "user": "integration_user",
    "created_at": "2026-02-03T23:11:18Z",
    "updated_at": "2026-02-03T23:11:18Z",
    "deleted_at": null
  }
}

Step 3: Add Additional Tables (Optional)

You can add more CMDB tables to your integration (up to eight total per integration).

curl -X POST "https://api.pagerduty.com/enrichment/integrations/servicenow/{integration_id}/tables" \
  -H "Authorization: Token token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cmdb_table": {
      "display_name": "Windows Servers",
      "ci_table_name": "cmdb_ci_win_server",
      "query_filter": null,
      "field_mappings": [
        {
          "servicenow_field": "name",
          "event_field": "source"
        },
        {
          "servicenow_field": "category",
          "event_field": "category"
        },
        {
          "servicenow_field": "fault_count",
          "event_field": "fault count"
        },
        {
          "servicenow_field": "cost_cc",
          "event_field": "cost cc"
        }
      ]
    }
  }'

Response: 201 Created

{
  "cmdb_table": {
    "id": "AGOCLVITO53U7HIANUORTDCGRQ",
    "display_name": "Windows Servers",
    "ci_table_name": "cmdb_ci_win_server",
    "query_filter": null,
    "field_mappings": [
      {
        "servicenow_field": "name",
        "event_field": "source"
      },
      {
        "servicenow_field": "category",
        "event_field": "category"
      },
      {
        "servicenow_field": "fault_count",
        "event_field": "fault count"
      },
      {
        "servicenow_field": "cost_cc",
        "event_field": "cost cc"
      }
    ],
    "status": "disabled",
    "created_at": "2026-02-03T23:27:27Z",
    "updated_at": "2026-02-03T23:27:27Z",
    "deleted_at": null
  }
}

Each table you add creates a new enrichment schema that can be used independently in your Event Enrichment rules.

Step 4: Update Table Configuration (Optional)

Modify field mappings, display names, or query filters for an existing table.

curl -X PUT "https://api.pagerduty.com/enrichment/integrations/servicenow/{integration_id}/tables/{table_id}" \
  -H "Authorization: Token token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Production Network Switches",
    "query_filter": "operational_status=1^u_environment=production",
    "field_mappings": [
      {
        "servicenow_field": "name",
        "event_field": "source"
      },
      {
        "servicenow_field": "operational_status",
        "event_field": "Operational Status"
      },
      {
        "servicenow_field": "sys_class_name",
        "event_field": "CI Class"
      },
      {
        "servicenow_field": "support_group.name",
        "event_field": "Support Team"
      }
    ]
  }'

Response: 200 OK

(Returns updated table configuration.)

Before enabling sync, you can update any aspect of the table configuration including the ci_table_name. However, changing the ci_table_name fundamentally changes which ServiceNow CMDB table is being synced, so if you need to sync a different table after enabling sync, you must create a new table configuration instead.

Step 5: Test Table Configuration

Before enabling data sync, validate your configuration by testing it against live ServiceNow data. This endpoint queries ServiceNow and returns up to 10 sample records.

curl -X GET "https://api.pagerduty.com/enrichment/integrations/servicenow/{integration_id}/tables/{table_id}/test" \
  -H "Authorization: Token token=YOUR_API_TOKEN"

Response: 200 OK

{
  "enrichment_data": [
    {
      "sys_id": "27e3a47cc0a8000b001d28ab291fa65b",
      "sys_created_on": "2007-11-09 20:49:13",
      "name": "OWA-SD-01",
      "sys_updated_on": "2025-08-04 12:11:27",
      "category": "Do not migrate to asset",
      "fault_count": "0",
      "sys_class_name": "Windows Server",
      "cost_cc": "USD"
    },
    {
      "sys_id": "3a172e820a0a0bb40034228e9f65f1be",
      "sys_created_on": "2008-10-26 09:57:57",
      "name": "PS LoadBal01",
      "sys_updated_on": "2025-08-04 12:11:30",
      "category": "Do not migrate to asset",
      "fault_count": "0",
      "sys_class_name": "Windows Server",
      "cost_cc": "USD"
    },
    {
      "sys_id": "eb6e54539831f6500ebf0f2f73f452a4",
      "sys_created_on": "2025-12-18 13:24:13",
      "name": "prod-db-server-01",
      "sys_updated_on": "2025-12-18 13:30:01",
      "category": "Hardware",
      "fault_count": "0",
      "sys_class_name": "Windows Server",
      "cost_cc": "USD"
    }
  ]
}

What This Validates

The test endpoint verifies:

• Credentials are valid and authentication succeeds.
• CMDB table exists and is accessible.
• Query filter syntax is correct (if specified).
• Mapped fields exist in the ServiceNow table.
• Data is returned in the expected format.

If the Test Fails, Check:

• ServiceNow credentials are correct.
• ServiceNow user has read permissions for the table.
• CMDB table name is spelled correctly.
• Query filter syntax is valid.
• All mapped ServiceNow fields exist in the table.

Step 6: Enable Data Sync

Once you have tested your configuration, enable data synchronization to begin syncing CMDB data to PagerDuty.

curl -X POST "https://api.pagerduty.com/enrichment/integrations/servicenow/{integration_id}/tables/{table_id}/enable" \
  -H "Authorization: Token token=YOUR_API_TOKEN"

Response: 200 OK

{
  "table_id": "AGOACUG5DR2ETBH5HBXUPP7KVI",
  "sync_enabled": true,
  "message": "Data sync enabled successfully"
}

After Enabling

• Data synchronization begins automatically.
• The enrichment schema is populated with CI data from ServiceNow.
• Data becomes available for use in Event Enrichment rules.
• Syncs occur periodically to keep data up-to-date.

Disable Data Sync

To stop synchronization for a table:

curl -X POST "https://api.pagerduty.com/enrichment/integrations/servicenow/{integration_id}/tables/{table_id}/disable" \
  -H "Authorization: Token token=YOUR_API_TOKEN"

Response: 200 OK

{
  "table_id": "AGOACUG5DR2ETBH5HBXUPP7KVI",
  "sync_enabled": false,
  "message": "Data sync disabled successfully"
}

View Integration Status

Retrieve your complete integration configuration including all tables, credentials, and current sync status for each table.

curl -X GET "https://api.pagerduty.com/enrichment/integrations/servicenow/{integration_id}" \
  -H "Authorization: Token token=YOUR_API_TOKEN"

Response: 200 OK

{
  "integration": {
    "id": "AGOACUG45VYBRJ6ZCGTBQFN5S4",
    "name": "Production CMDB Integration",
    "description": "Enrichment data from production ServiceNow instance",
    "cmdb_tables": [
      {
        "id": "AGOACUG5DR2ETBH5HBXUPP7KVI",
        "display_name": "Network Switches",
        "ci_table_name": "cmdb_ci_ip_switch",
        "query_filter": "operational_status=1",
        "field_mappings": [
          {
            "servicenow_field": "name",
            "event_field": "source"
          },
          {
            "servicenow_field": "operational_status",
            "event_field": "Operational Status"
          },
          {
            "servicenow_field": "support_group",
            "event_field": "Support Group"
          }
        ],
        "status": "active",
        "created_at": "2026-01-27T21:16:43Z",
        "updated_at": "2026-01-27T21:16:43Z",
        "deleted_at": null
      },
      {
        "id": "AGOCLVITO53U7HIANUORTDCGRQ",
        "display_name": "Windows Servers",
        "ci_table_name": "cmdb_ci_win_server",
        "query_filter": null,
        "field_mappings": [
          {
            "servicenow_field": "name",
            "event_field": "source"
          },
          {
            "servicenow_field": "category",
            "event_field": "category"
          }
        ],
        "status": "disabled",
        "created_at": "2026-02-03T23:27:27Z",
        "updated_at": "2026-02-03T23:27:27Z",
        "deleted_at": null
      }
    ],
    "credentials": {
      "id": "AGOCLRSKSB5OPMBBNIQC5X5R6E",
      "instance_endpoint": "https://your-instance.service-now.com",
      "user": "integration_user",
      "created_at": "2026-02-03T23:11:18Z",
      "updated_at": "2026-02-03T23:11:18Z",
      "deleted_at": null
    },
    "created_at": "2026-01-27T21:16:43Z",
    "updated_at": "2026-01-27T21:16:43Z"
  }
}

Use ServiceNow Data In Event Enrichment

Once your tables are synced, you can use them in Event Enrichment rules. The ServiceNow integration automatically creates enrichment schemas for each table configuration.

Find Your Schemas

In the Event Enrichment rule editor:

1. Create or edit an Event Enrichment.
2. Add a new rule and select Enrich events.
3. In the Join data from dropdown, look for schemas with your configured display names:
   • "Network Switches"
   • "Windows Servers"

Example Enrichment Rule

Scenario: Enrich events with support group information from your "Windows Servers" table.

Event Enrichment Rule Configuration

1. Condition: event.custom_details.hostname exists.
2. Action: Enrich events.
   1. Join data from: Windows Servers
   2. Match on: event.custom_details.hostname = source (the query field you mapped)
   3. Write enrichment data to: event.custom_details.cmdb_info

When an event comes in with a matching hostname, it will be enriched with category, fault count, and cost center data from ServiceNow.

Advanced Configuration

Specify Query Fields

By default, the integration automatically uses the name field as the query field — the field used to match incoming PagerDuty events to CI records in ServiceNow. This works well for most setups where events carry the CI name.

If your events use a different identifier (like sys_id, ip_address, or a custom field), or if you want to match on multiple fields simultaneously, you can explicitly designate which fields to use as query fields by adding "type": "query" to those field mappings.

Default Behavior (Auto-Detect)

When no type is specified on any field mapping, name is automatically used as the query field. All other fields provide enrichment context. This is the recommended approach for most integrations.

{
  "field_mappings": [
    { "servicenow_field": "name",              "event_field": "host" },
    { "servicenow_field": "support_group",     "event_field": "Support Group" },
    { "servicenow_field": "operational_status","event_field": "Operational Status" }
  ]
}

Explicit Query Field

Set "type": "query" on any field to use it as the query field instead of name. In this mode, name is not required and is treated as a regular enrichment field if included.

{
  "field_mappings": [
    { "servicenow_field": "sys_id",            "event_field": "ci_id",           "type": "query" },
    { "servicenow_field": "name",              "event_field": "host" },
    { "servicenow_field": "support_group",     "event_field": "Support Group" },
    { "servicenow_field": "operational_status","event_field": "Operational Status" }
  ]
}

Here, CI records are looked up by sys_id rather than name. Events must carry the ci_id field with a matching value.

Multiple Query Fields

You can designate up to three fields as query fields. When multiple query fields are configured, all of them must be present in the event for a match to occur. This is useful when a single field is not unique enough to identify a CI.

{
  "field_mappings": [
    { "servicenow_field": "name",           "event_field": "host",     "type": "query" },
    { "servicenow_field": "sys_class_name", "event_field": "ci_class", "type": "query" },
    { "servicenow_field": "support_group",  "event_field": "Support Group" },
    { "servicenow_field": "location",       "event_field": "Location" }
  ]
}

In this example, a CI is only matched if the event contains both a matching host and a matching ci_class.

View Field Types in Responses

The integration API always returns a type field on each field mapping in responses, showing how each field is configured (query or enriched).

Constraints

• At most three fields may have "type": "query".
• At least one field must be an enrichment field (no type specified).
• Only query is a valid value for type on requests — any other value is rejected.

Product Limits

• 1 ServiceNow integration per account.
• Up to 5 CMDB tables per integration.
• 2-20 field mappings per table.
• 1 credential set per account (shared across integrations).

Troubleshooting

Integration Creation Fails

Error: Account already has a ServiceNow integration

• Only one ServiceNow integration is allowed per account.
• Delete the existing integration or add tables to it instead.

Error: Invalid CMDB table name

• Verify the table exists in your ServiceNow instance.
• Check spelling and capitalization (table names are case-sensitive).
• Ensure the ServiceNow user has access to the table.

Credential Issues

Error: Authentication failed

• Verify the ServiceNow instance URL is correct (include https://).
• Check that username and password are correct.
• Ensure the ServiceNow user account is active and not locked.

Error: Insufficient permissions

• ServiceNow user must have read access to configured CMDB tables.
• Check role assignments in ServiceNow (typically requires itil or admin role).

Test Endpoint Failures

Returns empty array:

• Query filter may be too restrictive (no records match).
• Test the query filter in ServiceNow first to verify results.
• Try testing without a query filter to confirm table access.

Error on specific fields:

• Field name may be misspelled or not exist in the table.
• Check the ServiceNow table dictionary for correct field names.
• For dot-walked fields, verify the relationship exists.

Sync Issues

Data not appearing in enrichment:

• Verify sync is enabled for the table (check the integration status endpoint).
• Allow time for initial sync to complete (may take several hours for large tables).
• Check that credentials are still valid.

Data is stale:

• Syncs occur periodically (approximately once per hour).
• Consider updating query filters if specific records are not syncing.
• Verify ServiceNow data has actually changed.

Next Steps

After setting up your ServiceNow integration:

1. Create Event Enrichment rules using your synced CMDB data.
2. Test enrichment by sending sample events with matching query field values.
3. Monitor sync status to ensure data stays current.
4. Add more tables as needed for different CI types or teams.