ServiceNow CMDB Inbound API

ServiceNow CMDB Inbound API

Let’s start with a short reminder of what CMDB is. A CMDB helps an organization understand the relations between the components of a system and track their configurations. The CMDB is a fundamental component of the ITIL framework’s Configuration Management process.

ServiceNow Configuration Management Database (CMDB) contains the following tables:

  • The core Configuration Item [cmdb_ci] table, which stores the basic attributes of all CIs
  • The CI Relationship [cmdb_rel_ci] table, which defines all relationships between CIs. ServiceNow relationship rules use separate tables to define the relationships between specific CI base classes and dependent classes

CMDB implementation often involves federation, the inclusion of data into the CMDB from other partners and sources. Therefore, there is a need to provide and receive data from the partners and 3rd parties in order to maintain the data up to date, provide the service for the company and customers and also and keep your ITSM processes in good shape.

Now, we know already that we need to have an API to be able provide or receive CI’s data from 3rd parties. Of course, we have in ServiceNow OOB Table REST API, which allows you to perform create, read, update and delete (CRUD) operations on existing tables. Still, in most cases, especially in the CMDB area it doesn’t fulfill the organization’s security requirements, and the functionality itself is quite limited as well. One of the most significant limitations of Table API in the CMDB area is bypassing the Identification and Reconciliation engine (IRE). And why it’s an issue and why we should use IRE? Let’s briefly introduce IRE and observe what IRE actually is.

Why does it exist?

  • Because use of multiple data sources increases the risk of introducing inconsistencies through duplicate records

What does it do?

  • Provides a centralized framework for identifying and reconciling data from different data sources
  • Helps maintain the integrity of the CMDB when multiple data sources such as Discovery, import sets and manual entries are used to create and update CI records

Process flow of identification and reconciliation

Process flow of identification and reconciliation

Identification and Identification Rules

The Identification is the process of uniquely identifying Cis. Determinates if the CI already exists in the CMDB or a newly discovered CI must be added to the CMDB. The identification process relies on identification rules that apply to a CI class and comprises of one or more identifier entries that have a different priority.

Reconciliation and Reconciliation Rules

Reconciliation is the process of reconciling CIs and CI attributes by allowing only designated authoritative data sources to write to the CMDB. The CMDB is updated in real time as records are being processed. There is no staging area to verify the reconciliation activities before they are committed, and the process relies on reconciliation rules. The reconciliation rules can be set on CI table or attribute level and specify which data sources can update a table or a set of table attributes.

Now that we have an overview of IRE, we know its benefits, so we don’t think about Table API anymore. Instead, let’s focus on custom scripted CMDB Inbound API. The really easiest one could be like this:

An example of Scripted REST resource

Let’s imagine, that we would like to create/update Linux Server CI with several attributes. So, the incoming request is:

An example of the request body

Now, our main goal in scripted web service logic should be to do transformation, which will create from request body the JSON object in required structure and use it as input payload for Identification and Reconciliation API. So do not directly write to the CMDB, but enforce identification and reconciliation before data is stored in the CMDB to ensure that the data being written does not introduce inconsistencies.

Here we have this script in the Scripted REST Resource.

An example of the request body processing script in Scripted REST resource

Identification Rule for CI class ‘cmdb_ci_linux_server’:

Identification Rule and Identifier entries for table [cmdb_ci_linux_server]

If we would send our request, IR Engine will automatically do identification and reconciliation work. Based on the Identification Rule above, no CI has been matched, so from the API’s output payload we can see, that new Linux Server has been successfully created.

An output payload generated by IRE - CI hasn‘t been matched

If we would send the request once more, the CI would be already matched based on ‘’serial_number’ and operation would be “UPDATE”.

An output payload generated by IRE - CI has been matched


  • Identification and reconciliation API is used for creation of the data in ServiceNow CMDB
  • Identification and reconciliation API consumes input payload generated by scripted web service logic
  • Identification and reconciliation API returns output payload which informs about the result

Thank you for reading this article

Senior ServiceNow consultant