|
| 1 | +--- |
| 2 | +title: Set up ServiceNow CMDB Enrichment |
| 3 | +further_reading: |
| 4 | +- link: "/integrations/servicenow/" |
| 5 | + tag: "Documentation" |
| 6 | + text: "ServiceNow integration" |
| 7 | +- link: https://www.datadoghq.com/blog/servicenow-cmdb-it-management-datadog |
| 8 | + tag: Blog |
| 9 | + text: Manage your infrastructure with ServiceNow CMDB and Datadog |
| 10 | +--- |
| 11 | + |
| 12 | +## Overview |
| 13 | + |
| 14 | +The **ServiceNow Integration** uses ServiceNow's Configuration Management Database (CMDB) to enrich and contextualize your data within Datadog. This integration provides the following key capabilities: |
| 15 | + |
| 16 | +- [**Host Tagging**](#host-tagging): Enriches Datadog hosts with metadata from the ServiceNow CMDB, which allows for improved data organization and filtering. |
| 17 | +- [**Service Tagging**](#service-tagging): Populates the Datadog Service Catalog with services and their associated metadata from the ServiceNow CMDB. |
| 18 | +- [**Network Device Tagging**](#network-device-tagging): Adds tags to network devices monitored by Datadog, using metadata from the ServiceNow CMDB. |
| 19 | +- [**Reference Tables**](#reference-tables): Automatically enriches logs and events in Datadog with additional fields from ServiceNow CIs by mapping value fields to a primary key. |
| 20 | + |
| 21 | +## Host tagging |
| 22 | + |
| 23 | +Enrich your Datadog hosts with ServiceNow CMDB metadata through host tagging. |
| 24 | +To enable ingestion of host tags: |
| 25 | + |
| 26 | +1. In ServiceNow, configure a [Query Builder][1] query that returns all of the hosts you wish to tag in Datadog. Schedule the query to execute at your desired refresh interval and save it. |
| 27 | +1. Navigate to Datadog's ServiceNow integration tile. In the **Configure** section, in the **CMDB Enrichment** tab, select **Host Tagging**. |
| 28 | +1. Under **Query Configuration**, click **Add New Query**. |
| 29 | +1. Select the **ServiceNow Instance** and the **Query** from the dropdown menus. |
| 30 | +1. Select a value for the **Hostname Column** that maps your query's root CI hostname field to Datadog's hostname field. The dropdown options come from the starting node of your querybuilder query. |
| 31 | +1. Select any optional field name remapping with **Column Name Maps**. By default, tags are applied to the host in the format `tagName:columnValue`, where `tagName` is a combination of the table name and the column name. |
| 32 | +1. Click **Save**. |
| 33 | + |
| 34 | +Expect host tags to populate in Datadog shortly after your queries' scheduled executions. |
| 35 | +<!-- ![Screenshot of Host info tab showing ServiceNow host tags][image1] --> |
| 36 | + |
| 37 | +Monitor the ingestion process in the Datadog [Events Explorer][2] by scoping your search query on `source:servicenow`. |
| 38 | +<!-- ![Screenshot showing one running ingestion][image2] --> |
| 39 | + |
| 40 | +### Additional Non-CMDB field tagging |
| 41 | + |
| 42 | +Some ServiceNow tables are non-CMDB and cannot be selected in the Query Builder. To enrich Datadog hosts with tags from these tables, click **Additional Fields** on the configuration tile and configure a host tagging query as described above, providing a full dot-walked path. Paths should start from the first attribute name on the root table configured for the query. For example, entering `vendor.manufacturer.name` for a query with root CI `cmdb_ci_server` populates hosts with the tag `cmdb_ci_server_manufacturer_name`. |
| 43 | + |
| 44 | +**Note**: Only dot-walkable paths that are supported by the ServiceNow Table API are available for use in Additional Fields. Many-to-many relationships may not work out of the box and may require additional configuration. |
| 45 | + |
| 46 | +## Service tagging |
| 47 | + |
| 48 | +Enrich your Datadog Service Catalog with ServiceNow CMDB metadata through service tagging. |
| 49 | +With service tagging, you can populate your Datadog [Service Catalog][3] with services from your ServiceNow CMDB. |
| 50 | + |
| 51 | +To enable ingestion of service data: |
| 52 | + |
| 53 | +1. In ServiceNow, configure a [Query Builder][1] query that returns all of the services with which you wish to enrich the Service Catalog. Schedule the query to execute at your desired refresh interval and save it. |
| 54 | +1. Navigate to Datadog's ServiceNow integration tile. In the **Configure** section, in the **CMDB Enrichment** tab, select **Service Tagging**. |
| 55 | +1. Under **Query Configuration**, click **Add New Query**. |
| 56 | +1. Select the **ServiceNow Instance** and the **Query** from the dropdown menus. |
| 57 | +1. Select a value from the **Service Name Column** dropdown menu. The value matches the column name on your query's root service CI, and populates the service name in the service catalog. |
| 58 | +1. Configure schema mappings to pull additional metadata about your service into the service catalog. See [Service definitions][4] for details. For Datadog to accept the ingestion, each field in the mapping needs to be of the correct type to map to the service catalog service definition schema. |
| 59 | +1. Click **Save**. |
| 60 | + |
| 61 | +Expect to see service data populated in Datadog a few minutes after your queries' scheduled executions. To view ingestion errors, go to the [Events Explorer][2] and search for events with `source:servicenow`. |
| 62 | +<!-- ![Screenshot of the Service Configuration panel showing metadata populated from ServiceNow][image3] --> |
| 63 | + |
| 64 | +## Network device tagging |
| 65 | + |
| 66 | +Add tags to your network devices in Datadog populated with data from your ServiceNow CMDB. |
| 67 | + |
| 68 | +With device tagging, you can dynamically enrich network devices monitored by Datadog [Network Device Monitoring][5] with device metadata from your ServiceNow CMDB. |
| 69 | + |
| 70 | +To enable ingestion of device tags: |
| 71 | + |
| 72 | +1. Configure a [Query Builder][1] query in your ServiceNow instance. Make sure it is returning the device IP address. Schedule the query to execute at your desired refresh interval. |
| 73 | +1. If you are using a custom IP namespace in Datadog, you need to add it to ServiceNow. Create a column on the Network device CI called `u_dd_device_namespace`, populated by the corresponding namespace for each device. If this column is not present, ServiceNow uses the default namespace. |
| 74 | +1. After the query is saved in ServiceNow, go to Datadog's ServiceNow integration tile. In the **Configure** section, in the **CMDB Enrichment** tab, select **Device Tagging**. |
| 75 | +1. Under **Query Configuration**, click **Add New Query**. |
| 76 | +1. Select the **ServiceNow Instance** and the **Query** from the dropdown menus. |
| 77 | +1. Select the **IP Address** column that maps your query's IP Address field to Datadog's IP Address field. |
| 78 | +1. Select any optional field name remappings. |
| 79 | +1. Click **Save**. |
| 80 | + |
| 81 | +You can expect to see network device tags populated in Datadog within a few minutes after your queries' scheduled executions. Any ingestion errors are reported through events viewable in your events explorer. |
| 82 | + |
| 83 | +Monitor the ingestion process in the Datadog [Events Explorer][2] by scoping your search query on `source:servicenow`. |
| 84 | +<!-- ![Screenshot showing one running ingestion][image4] --> |
| 85 | + |
| 86 | +## Reference Tables |
| 87 | + |
| 88 | +Use [Reference Tables][7] to automatically enrich logs and events with additional fields from your ServiceNow CIs. With Reference Tables, you can map sets of value fields to a primary key, such as a hostname, and automatically append these fields to all logs or events that contain the specified key. |
| 89 | +To enable ingestion of Reference Tables: |
| 90 | + |
| 91 | +1. Configure a [Query Builder][8] query in your ServiceNow instance. Schedule the query to run at your desired refresh interval and save it. |
| 92 | +1. Select **Add New Query** and choose your query from the dropdown menu. |
| 93 | +1. In the primary key dropdown, select the column name you want to use as your primary key.<br />Optionally, create a [Processing Pipeline][9] with this primary key to enrich and correlate logs and events. |
| 94 | +1. Enter a name for your reference table. The Reference Table name must be unique. |
| 95 | +1. Click **Save**. The [Reference Table][7] populates with the data from the query shortly after saving. |
| 96 | + |
| 97 | +### Additional non-CMDB fields in Reference Tables |
| 98 | + |
| 99 | +Some ServiceNow tables are non-CMDB and cannot be selected in the Query Builder. To include data from these tables, you can use **Additional Fields** by specifying a **full dot-walked path**. These fields are added as extra columns to the reference table, along with the ones defined by the Query Builder. |
| 100 | + |
| 101 | +**Note**: Only paths supported by the ServiceNow Table API are available for use in Additional Fields. The generated columns are based on the root table name and the last two columns of the field spec. For example, `vendor.manufacturer.name` generates a column named `cmdb_ci_server_manufacturer_name`, and `location.city` generates a column named `cmdb_ci_server_location_city` assuming a root table of `cmdb_ci_server`. |
| 102 | + |
| 103 | +## Troubleshooting |
| 104 | + |
| 105 | +For tagging to work correctly, ensure that the following are true in your system: |
| 106 | + |
| 107 | +- The user who created and executes the Query Builder query matches a username in your Datadog configuration. The user in ServiceNow must have the role `cmdb_query_builder_read`. |
| 108 | +- The number of results returned by your query must be less than or equal to the `glide.cmdb.query.max_results_limit` setting in ServiceNow. By default, the maximum number of results is 10000. To change the setting, go to **Configuration** > **CMDB Properties** > **Query Builder Properties**. |
| 109 | +- All CIs configured in your Query Builder query must have a `1` label. This ensures you have not created any duplicate CIs, which the parser does not support. |
| 110 | + |
| 111 | +## Limitations |
| 112 | + |
| 113 | +- Ingestion is limited to 100k hosts per execution. |
| 114 | +- Updates to hosts and devices are throttled to a few thousand per hour. Take this limit into consideration when choosing your schedule interval. |
| 115 | +- Host aliases in Datadog are case sensitive. Your ingested CMDB hostnames must exactly match the corresponding hostnames in Datadog. |
| 116 | +- Network device tagging is limited to [SNMP devices][6]. |
| 117 | +- Deletions and schema updates of existing tables are not supported. |
| 118 | + |
| 119 | +## Further reading |
| 120 | + |
| 121 | +{{< partial name="whats-next/whats-next.html" >}} |
| 122 | + |
| 123 | +[1]: https://docs.servicenow.com/bundle/xanadu-servicenow-platform/page/product/configuration-management/concept/cmdb-query-builder-landing-page.html |
| 124 | +[2]: https://app.datadoghq.com/event/explorer |
| 125 | +[3]: https://docs.datadoghq.com/tracing/service_catalog/ |
| 126 | +[4]: https://docs.datadoghq.com/tracing/service_catalog/adding_metadata/ |
| 127 | +[5]: https://docs.datadoghq.com/network_monitoring/devices/ |
| 128 | +[6]: https://docs.datadoghq.com/network_monitoring/devices/snmp_metrics/ |
| 129 | +[7]: https://app.datadoghq.com/reference-tables |
| 130 | +[8]: https://docs.servicenow.com/bundle/rome-servicenow-platform/page/product/configuration-management/task/use-cmdb-query-builder.html |
| 131 | +[9]: https://app.datadoghq.com/event/pipelines |
0 commit comments