How to debug the Identification and Reconciliation Engine using background scripts - Support and Troubleshooting

How to debug the Identification and Reconciliation Engine using background scripts Summary .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: #000000; } span { font-size: 12pt; font-family: Lato; color: #000000; } h2 { font-size: 24pt; font-family: Lato; color: black; } h3 { font-size: 18pt; font-family: Lato; color: black; } h4 { font-size: 14pt; font-family: Lato; color: black; } a { font-size: 12pt; font-family: Lato; color: #00718F; } a:hover { font-size: 12pt; color: #024F69; } a:target { font-size: 12pt; color: #032D42; } a:visited { font-size: 12pt; color: #00718f; } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } Troubleshoot unexpected Discovery or SCCM results by running Identification and Reconciliation Engine (IRE) API calls from background scripts to generate detailed debug information. When Discovery or integration processes do not insert or update records as expected, you can use IRE API calls in background scripts to isolate debug output from other system activity. This approach provides cleaner log data than searching the system log during active Discovery jobs.

Release .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: #000000; } span { font-size: 12pt; font-family: Lato; color: #000000; } h2 { font-size: 24pt; font-family: Lato; color: black; } h3 { font-size: 18pt; font-family: Lato; color: black; } h4 { font-size: 14pt; font-family: Lato; color: black; } a { font-size: 12pt; font-family: Lato; color: #00718F; } a:hover { font-size: 12pt; color: #024F69; } a:target { font-size: 12pt; color: #032D42; } a:visited { font-size: 12pt; color: #00718f; } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } All supported releases

Instructions .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: #000000; } span { font-size: 12pt; font-family: Lato; color: #000000; } h2 { font-size: 24pt; font-family: Lato; color: black; } h3 { font-size: 18pt; font-family: Lato; color: black; } h4 { font-size: 14pt; font-family: Lato; color: black; } a { font-size: 12pt; font-family: Lato; color: #00718F; } a:hover { font-size: 12pt; color: #024F69; } a:target { font-size: 12pt; color: #032D42; } a:visited { font-size: 12pt; color: #00718f; } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } Before you begin Warning: The scripts in this article insert or update records. Perform this troubleshooting in a non-production instance only . If you must debug in production, verify you have permission to insert or update records.

Requirements

IRE input payload (see Finding the IRE payload section) User with admin privileges Access to System Definition > Scripts - Background Note: Not all users have access to background scripts or the APIs used in these examples.

Alternative method

You can also use the Identification Simulation module at Configuration > Identification/Reconciliation > Identification Simulation . However, this module does not provide the same level of debug data that may be necessary to identify the root cause of an issue.

Why use background scripts

Debug information is available in the system log, but if Discovery jobs are running, the data can be difficult to isolate. Debug statements from background scripts are isolated to your session, making the output easier to analyze.

Find the IRE payload The IRE input payload is logged each time it is sent to the API.

Go to System Logs > System Log > All . Search for records where Message contains " input = ". If the payload is not found or the event occurred in the past, reprocess the ECC Queue input or rerun Discovery, then search again. Enable IRE debug logging If the IRE payload is not logged, add the following system property:

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

If the IRE payload is still not found after adding this property, the process inserting or updating records is not using the IRE API.

Run the debug script Use the following script to run IRE API calls from background scripts:

var payload = ; var discoverySource = "ServiceNow"; var output = SNC.IdentificationEngineScriptableApi.createOrUpdateCI(discoverySource, JSON.stringify(payload)); gs.print(output);

Payload format

The IRE_Payload must be a JSON object (not a string) in the following format:

{"fld1":"val1","fld2":"val2"}

Sample payload

{"items":[{"className":"cmdb_ci_win_server","values":{"company":"86c1f3193790200044e0bfc8bcbe5d95","install_status":"1","ip_address":"10.20.30.41","location":"a63c49b037d0200044e0bfc8bcbe5dd9","mac_address":"ABCD1234","manufacturer":"0c43c22bc611227500002515e25bf079","model_id":"4431c26b37913000158bbfc8bcbe5d0d","name":"SNCTest Win Server 100","operational_status":"1","ram":"2048","serial_number":"SNC123456789"}}]}

Example script with payload The following example includes gs.trace(true) to display SQL statements. This is not necessary in every scenario but can help identify query-level issues.

var payload = {"items":[{"className":"cmdb_ci_win_server","values":{"company":"86c1f3193790200044e0bfc8bcbe5d95","install_status":"1","ip_address":"10.20.30.40","location":"a63c49b037d0200044e0bfc8bcbe5dd9","mac_address":"ABCD1234","manufacturer":"0c43c22bc611227500002515e25bf079","model_id":"4431c26b37913000158bbfc8bcbe5d0d","name":"SNCTest Win Server 100","operational_status":"1","ram":"2048","serial_number":"SNC123456789"}}]};

var discoverySource = "ServiceWatch"; gs.trace(true); var output = SNC.IdentificationEngineScriptableApi.createOrUpdateCI(discoverySource, JSON.stringify(payload)); gs.trace(false); gs.print(output);

Example Call Output The following output shows a typical IRE debug response. Key lines are explained after the output.

identification_engine : IdentificationEngine::process: Pass=1 identification_engine : addAttempt [{"className":"cmdb_ci_win_server","values":{"operational_status":"1","discovery_source":"ServiceWatch","install_status":"1","mac_address":"ABCD1234","name":"SNCTest002","serial_number":"SNC123456789","company":"86c1f3193790200044e0bfc8bcbe5d95","location":"a63c49b037d0200044e0bfc8bcbe5dd9","ip_address":"10.20.30.41","model_id":"4431c26b37913000158bbfc8bcbe5d0d","manufacturer":"0c43c22bc611227500002515e25bf079","ram":"2048"},"internal_id":"37dadd3adbd674104a9a53ca1184b9ac","sys_object_source_info":{"source_name":"ServiceWatch"},"settings":{},"sys_ire_info":{"ire_received_time":"2021-09-03 15:33:31"}}] - [sys_object_source] SKIPPED identification_engine : addAttempt [{"className":"cmdb_ci_win_server","values":{"operational_status":"1","discovery_source":"ServiceWatch","install_status":"1","mac_address":"ABCD1234","name":"SNCTest002","serial_number":"SNC123456789","company":"86c1f3193790200044e0bfc8bcbe5d95","location":"a63c49b037d0200044e0bfc8bcbe5dd9","ip_address":"10.20.30.41","model_id":"4431c26b37913000158bbfc8bcbe5d0d","manufacturer":"0c43c22bc611227500002515e25bf079","ram":"2048"},"internal_id":"37dadd3adbd674104a9a53ca1184b9ac","sys_object_source_info":{"source_name":"ServiceWatch"},"settings":{},"sys_ire_info":{"ire_received_time":"2021-09-03 15:33:31"}}] - [Rule id:c12f9be8c3400200d8d4bea192d3aea6|cmdb_ci_hardware|cmdb_serial_number|[serial_number, serial_number_type]] SKIPPED identification_engine : addAttempt [{"className":"cmdb_ci_win_server","values":{"operational_status":"1","discovery_source":"ServiceWatch","install_status":"1","mac_address":"ABCD1234","name":"SNCTest002","serial_number":"SNC123456789","company":"86c1f3193790200044e0bfc8bcbe5d95","location":"a63c49b037d0200044e0bfc8bcbe5dd9","ip_address":"10.20.30.41","model_id":"4431c26b37913000158bbfc8bcbe5d0d","manufacturer":"0c43c22bc611227500002515e25bf079","ram":"2048"},"internal_id":"37dadd3adbd674104a9a53ca1184b9ac","sys_object_source_info":{"source_name":"ServiceWatch"},"settings":{},"sys_ire_info":{"ire_received_time":"2021-09-03 15:33:31"}}] - [Rule id:fb27f69cc3000200d8d4bea192d3ae67|cmdb_ci_hardware|[serial_number]] MATCHED identification_engine : createOrUpdateCI: Matched 1 records and 0 relations in 4msec identification_engine : Reconciliation: update to field 'name' of CI 'a853dd72dbd674104fa1c9db1396190e' was skipped because of rules [60d9117adbd674104fa1c9db13961986] defined in cmdb_reconciliation_definition identification_engine : Reconciliation: cmdb_ci_win_server(name) field update skipped for Data Source ServiceWatch identification_engine : Commit: UPDATE cmdb_ci_win_server : a853dd72dbd674104fa1c9db1396190e identification_engine : Processed 1 records and 0 relations in 4msec + 135msec (waited 0msec for mutex) identification_engine : logId:[3bda95ba17d67410854244fa7a3ee1c2] Processed payload from ServiceWatch. Using options: {partial_payloads:false,partial_commits:false,deduplicate_payloads:false,generate_summary:false} identification_engine : logId:[3bda95ba17d67410854244fa7a3ee1c2] Input = {"items":[{"className":"cmdb_ci_win_server","values":{"operational_status":"1","install_status":"1","mac_address":"ABCD1234","name":"SNCTest002","company":"86c1f3193790200044e0bfc8bcbe5d95","location":"a63c49b037d0200044e0bfc8bcbe5dd9","serial_number":"SNC123456789","ip_address":"10.20.30.41","model_id":"4431c26b37913000158bbfc8bcbe5d0d","manufacturer":"0c43c22bc611227500002515e25bf079","ram":"2048"},"sys_object_source_info":{"source_name":"ServiceWatch"},"sys_ire_info":{"ire_received_time":"2021-09-03 15:33:31"}}]} identification_engine : logId:[3bda95ba17d67410854244fa7a3ee1c2] Output = {"items":[{"className":"cmdb_ci_win_server","operation":"UPDATE","sysId":"a853dd72dbd674104fa1c9db1396190e","maskedAttributes":["name"],"identifierEntrySysId":"fb27f69cc3000200d8d4bea192d3ae67","identificationAttempts":[{"info":"sys_object_source SKIPPED","identifierName":"","attemptResult":"SKIPPED","attributes":[],"hybridEntryCiAttributes":[]},{"identifierName":"Hardware Rule","attemptResult":"SKIPPED","attributes":["serial_number","serial_number_type"],"searchOnTable":"cmdb_serial_number","hybridEntryCiAttributes":[]},{"identifierName":"Hardware Rule","attemptResult":"MATCHED","attributes":["serial_number"],"searchOnTable":"cmdb_ci_hardware","hybridEntryCiAttributes":[]}],"info":[],"errorCount":0,"markers":[],"mergedPayloadIds":[],"warningCount":0,"inputIndices":[0]}],"additionalCommittedItems":[],"relations":[],"additionalCommittedRelations":[]} identification_engine : Identification Engine Total execution time 146msec *** Script: {"items":[{"className":"cmdb_ci_win_server","operation":"UPDATE","sysId":"a853dd72dbd674104fa1c9db1396190e","maskedAttributes":["name"],"identifierEntrySysId":"fb27f69cc3000200d8d4bea192d3ae67","identificationAttempts":[{"info":"sys_object_source SKIPPED","identifierName":"","attemptResult":"SKIPPED","attributes":[],"hybridEntryCiAttributes":[]},{"identifierName":"Hardware Rule","attemptResult":"SKIPPED","attributes":["serial_number","serial_number_type"],"searchOnTable":"cmdb_serial_number","hybridEntryCiAttributes":[]},{"identifierName":"Hardware Rule","attemptResult":"MATCHED","attributes":["serial_number"],"searchOnTable":"cmdb_ci_hardware","hybridEntryCiAttributes":[]}],"info":[],"errorCount":0,"markers":[],"mergedPayloadIds":[],"warningCount":0,"inputIndices":[0]}],"additionalCommittedItems":[],"relations":[],"additionalCommittedRelations":[],"hasError":false,"hasWarning":false}

Key observations from this output:

The serial_number identification rule matched an existing record The name field was not updated because a reconciliation rule prevented the update The final operation was UPDATE (not INSERT), confirming the record was found Troubleshooting examples Example 1: SCCM creates duplicate records instead of updating existing record Scenario: A Computer record exists with Serial Number "ABCDE12345". When the SCCM transformation runs, it should match the existing record. Instead, it creates a duplicate. Subsequent runs match the newly created record.

Analysis: After retrieving the IRE payload from the system log and running the script with gs.trace(true), review the SQL query generated when evaluating the Serial Number identifier:

SELECT cmdb0.sys_id, cmdb0.sys_mod_count, cmdb0.sys_class_name, cmdb0.serial_number FROM (cmdb cmdb0 INNER JOIN cmdbpar1cmdbpar1 cmdb par1cmdbpar10 ON cmdb0. sys_id = cmdb$par10.sys_id ) WHERE cmdb0.sys_class_path LIKE '/!!/!2%' AND ((cmdb0.serial_number = 'ABCDE12345')) AND cmdb$par10.duplicate_of IS NULL

Root cause: The condition duplicate_of IS NULL caused the query to fail. The existing record was marked as a duplicate of another record at some point, so the duplicate_of field was not empty. IRE could not find the existing record and created a new one.

Resolution : Clear the duplicate_of field on the original record, or merge the duplicate records.

Example 2: Discovery does not update CI name in SQL Instance class Scenario: MSSQL server Discovery using modified patterns should populate the SQL Instance name per company requirements. However, the SQL Instance name is not updated after Discovery runs.

Analysis: Retrieve the IRE payload and run it from background scripts. The debug output shows:

identification_engine : Reconciliation: update to field 'tcp_port' of CI '6bce7dcfdb08b7c479cca9a5ca961910' was skipped because of rules [3104a82e9f503200c7445f9bc32e7054, a0d77a059311020062281f10077ffb32] defined in cmdb_reconciliation_definition identification_engine : Reconciliation: update to field 'name' of CI '6bce7dcfdb08b7c479cca9a5ca961910' was skipped because of rules [3104a82e9f503200c7445f9bc32e7054] defined in cmdb_reconciliation_definition identification_engine : Reconciliation: cmdb_ci_db_mssql_instance(tcp_port) field update skipped for Data Source Service-now identification_engine : Reconciliation: cmdb_ci_db_mssql_instance(name) field update skipped for Data Source Service-now identification_engine : Commit: UPDATE cmdb_ci_db_mssql_instance : 6bce7dcfdb08b7c479cca9a5ca961910

Root cause: No reconciliation rules exist for the legacy "Service-now" Discovery source. The update to the existing SQL Instance record was blocked.

Resolution: Create reconciliation rules that include the "Service-now" Discovery source, or update the Discovery source name to match existing reconciliation rules.

Example 3: Review business rules executed during script To see which business rules are triggered when the script runs:

Go to System Diagnostics > Script Debugger . Select the Session Log tab. Select Settings and enable Business Rule debug . In a separate browser tab, go to System Definition > Scripts - Background and run your script. Return to the Script Debugger and review the session log for the business rules that were run. Review the script output for IRE debug information. Note : You can enable additional session debug settings by selecting the corresponding checkboxes.