How to build and troubleshoot an IRE payload for CMDB - Support and Troubleshooting

How to build and troubleshoot an IRE payload for CMDB .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } }

Learn how the CMDB model, Identification and Reconciliation Engine (IRE), and identification simulation work together to build and validate CI payloads. This article covers the CMDB class configuration, IRE payload structure, identification simulation, and common payload errors with solutions.

In this article: CMDB model Identification and Reconciliation Engine Building a payload Payload errors Related links CMDB model The CMDB model for a class includes the following components:

Class description — Defines the class and its attributes.

Identification rules and identifier entries — The set of rules the IRE uses to determine if a configuration item (CI) already exists in the database.

Reconciliation rules — Specify which discovery sources can update class attributes and the precedence order among those sources.

Dependent relationships — The identifier for a class determines whether the class is independent or dependent. Independent classes can be sent to the IRE without any relationships. Dependent classes require a relationship and information about the CI they depend on in the same payload.

Inclusion rules — During duplicate detection of independent CIs, the IRE processes only the CIs that satisfy the identification inclusion rules.

Check the configuration for a class

Go to Configuration > CI Class Manager .

Search for the class of interest. For example, search for Windows Server

Select an option to view the rules for this class:

Select Identification Rule to view the identification rules. The identification rule indicates whether the class is independent (can be identified without relationships) or dependent. The Identifier Entries section lists the identifier entries the IRE attempts in priority order. Each entry shows the search table, priority value, and the attributes used for matching. For example, the Windows Server class has four identifier entries ranging from Priority 100 (Serial Number) to Priority 400 (Network Adapter).

Select Reconciliation Rule to view the reconciliation rules. Reconciliation rules determine which discovery sources are allowed to populate attributes and in which order. Each rule shows the attributes it applies to, the discovery source and priority, and the target class. For example, the Windows Server class has one reconciliation rule that allows the ServiceNow data source (Priority 10) to update all attributes.

Select Dependent Relationships to view required relationships for a dependent class. The diagram shows the parent class, relationship type, and the dependent class. For example, the Network Adapter class depends on Hardware through an Owns relationship. Dependent classes require this relationship information in the payload for the IRE to process them.

Identification and Reconciliation Engine The IRE is a centralized framework that performs identification and reconciliation processes across different data sources. The IRE uses identification rules, reconciliation rules, and data source rules when processing incoming data before inserting it into the CMDB.

The IRE helps maintain data integrity in the CMDB by:

Preventing duplicate CIs through unique identification

Reconciling CI attributes by allowing only authoritative data sources to write to the CMDB

Building a payload Use identification simulation to determine payload contents

Go to Configuration > Identification/Reconciliation > Identification Simulation .

Select Start from the Start with CI Class box.

Populate the Data Source , Class , Attributes , and Container fields.

Data source — The source sending data to the IRE (for example, ImportSet).

Class — The CI class that will be passed to the IRE (for example, Network Adapter).

Criterion attributes — The attributes used to identify the CI. Fill at least one set of criterion attributes.

Container level 1 — The parent class this CI is related to (required for dependent classes).

Select Generate Script . The right panel displays the payload built by the identification simulation with the required data. In this example, the form includes a Network Adapter CI (with mac_address and name attributes) and a Windows Server container (with serial_number), and the generated payload includes both CIs and their Owns::Owned by relationship.

Select Run Simulation to pass the payload to the IRE for processing. The generated payload contains two main sections:

items — The CI data, including the class name and attribute values for each CI in the payload.

relations — The required relationships between CIs (for example, an Owns::Owned by relationship linking the parent Windows Server to the child Network Adapter).

Note : The identification simulation does not insert or update records. It validates the payload without making changes to the database.

Payload errors For a complete list of IRE error codes, see Identification engine error messages .

Enable debug logging

To log the payload to the system logs (syslog table), add the following system property:

Property name: glide.cmdb.logger.source.identification_engine Property value: info,warn,error,debug,debugVerbose Warning: Revert the property to the default value of info,warn,error when you are finished debugging.

Issue 01 — Dependent class missing required relationships The following payload produces an error because the dependent class does not include the required relationships:

{ "items": [ { "className": "cmdb_ci_network_adapter", "lookup": [], "values": { "mac_address": "08:00:27:66:50:99", "name": "ETH8" } }, { "className": "cmdb_ci_win_server", "lookup": [], "values": { "serial_number": "ABC123!ABC123!" } } ] } The IRE returns the following error:

In payload no relations defined for dependent class [cmdb_ci_network_adapter] that matches any containment/hosting rules: [cmdb_ci_network_adapter >> Owned by >> cmdb_ci_hardware]. Add appropriate relations in payload for...

The error message contains two parts:

Cause : The dependent class does not have the required relationships (containment or hosting rules). The message lists the valid relationships that can be passed in the payload. Fix : Add the appropriate relations to the payload. To resolve this error, either adjust the payload manually or use the identification simulation to build a valid payload. The following corrected payload includes the missing relationship:

{ "items": [ { "className": "cmdb_ci_network_adapter", "lookup": [], "values": { "mac_address": "08:00:27:66:50:99", "name": "ETH8" } }, { "className": "cmdb_ci_win_server", "lookup": [], "values": { "serial_number": "ABC123!ABC123!" } } ], "relations": [ { "type": "Owns::Owned by", "parent": 1, "child": 0 } ] }

After adding the relationship, the IRE processes the payload without errors. Because this network adapter did not exist, a new record is created:

{ "className": "cmdb_ci_network_adapter", "operation": "INSERT", "identificationAttempts": [ { "info": "sys_object_source SKIPPED", "identifierName": "", "attemptResult": "SKIPPED", "attributes": [], "hybridEntryCiAttributes": [] }, { "identifierName": "Network Adapter", "attemptResult": "NO_MATCH", "attributes": [ "mac_address", "name" ], "searchOnTable": "cmdb_ci_network_adapter", "hybridEntryCiAttributes": [] } ], "info": [], "errorCount": 0, "mergedPayloadIds": [], "warningCount": 0, "inputIndices": [ 0 ], "markers": [] } Issue 02 — CI field not updated due to reconciliation rules In this example, a payload attempts to update the name field of a Windows Server CI. However, the field is not updated after the IRE processes the payload.

Step 1: Verify the field is populated in the payload

Set the identification engine to debugVerbose to confirm the field value was included in the payload. In the syslog, verify that the target field (in this case, name ) was populated with the intended value.

If the field is populated in the payload but the record is not updated, proceed to the next step.

Step 2: Review the debug logs for reconciliation messages

With the identification engine still set to debug, review the system logs filtered by source identification_engine at the time of the failed update.

If the log indicates that the IRE did not update the field based on the data source, check the reconciliation rules for the class.

Step 3: Check reconciliation rules

Review the reconciliation rules for the class in CI Class Manager. In this example, a reconciliation rule for the Windows Server class allows only the data source ServiceNow to update the class.

To allow the payload data source to update the target CI:

Review the existing reconciliation rule to determine if the source restriction is intentional. Create or add a rule to allow the data source to update this class.

Issue 03 — Issue is not related to the IRE If the payload contains the required data and no reconciliation rules block the update, the issue is likely caused by business rules or access control lists (ACLs) rather than the IRE. To investigate further, run the identification engine directly through a background script.

For instructions, see How to debug the Identification and Reconciliation Engine using background scripts .

Related links How to debug the Identification and Reconciliation Engine using background scripts How to troubleshoot duplicate CMDB CI records Identification rules Create an identification inclusion rule Reconciliation rules