IdentifyReconcile API - POST

Insert or update configuration items in the CMDB based on identification and reconciliation rules. Use this API instead of updating the CMDB directly.

URL format

Versioned URL: /api/now/v1/identifyreconcile

Default URL: /api/now/identifyreconcile

Supported request parameters

Table 1. Parameters
Parameter Description
sysparm_data_source Identifies the source of the CI information. This must be one of the choice values defined for the discovery_source field of the cmdb_ci table.

Headers

Table 2. Request headers
Header Description
Accept Specify application/json
Content-Type Specify application/json
Table 3. Response headers
Header Description

Input payload

A JSON formatted string of configuration items to be added or updated. Each input string is in the format  'items: [{}], relations:[{}]', where each item within the items and relations lists contains name-value pairs.
The possible name-value pairs within the items list are:
  • className - the sys_class_name of the CI to be created or updated.
  • values:{} - the field information for the CI as name-value pairs, where the name is the field name.
  • lookup:[{}] - a list of records with each item having name-value pairs like the items list.
The possible name-value pairs within the relations list are:
  • parent - index of the parent item in the dependency relation
  • child - index of the child item in the dependency relation
  • type - the relationship type. This is one of the name field values from the cmdb_rel_type table.

Sample input payload

The sample input is a JSON string that contains a list of configuration items and a list of relationships that exist between these configuration items.

{"items": [ {"className":"cmdb_ci_web_server", 
                    "values": {"name":"apache linux den 200", 
                             "running_process_command": "xyz",  
                             "running_process_parameters": "abc", "tcp_port":"3452"}}, 
                    {"className":"cmdb_ci_linux_server", 
                     "values": {"name":"lnux100", "ram":"2048"}}],
           "relations":[{"parent": "0", "child": "1", "type": "Runs on::Runs"}]
              }

Response payload

A JSON formatted string that is a list of results for the configuration items in the input string. Each result string is in the format  'items: [{}], relations:[{}]', where each item within the items and relations lists contains name-value pairs.
The possible name-value pairs within the items list are:
  • className- the sys_class_name for the CI to be updated or created.
  • operation, which is one of INSERT, UPDATE, UPDATE_WITH_UPGRADE, UPDATE_WITH_DOWNGRADE, UPDATE_WITH_SWITCH, DELETE, NO_CHANGE
  • sysId - the sys_id of the CI that was updated or created.
  • relatedSysIds - a list of sys_id values of CIs used during lookup based identification.
  • identifierEntrySysId - sys_id of identifier entry used during matching.
  • errors - a list of errors in the format of (error, message string), where error can be ABANDONED, INVALID_INPUT_DATA, IDENTIFICATION_RULE_MISSING, IDENTIFICATION_RULE_FOR_LOOKUP_MISSING, NO_LOOKUP_RULES_FOR_DEPENDENT_CI, NO_CLASS_NAME_FOR_INDEPENDENT_CI, MISSING_DEPENDENCY, MULTIPLE_DEPENDENCIES, MULTIPLE_DUPLICATE_RECORDS, RELATION_CHAIN_ENDS_AT_QUALIFIER, QUALIFICATION_LOOP, TYPE_CONFLICT_IN_QUALIFICATION, MULTI_MATCH, REQUIRED_ATTRIBUTE_EMPTY, RECLASSIFICATION_NOT_ALLOWED
  • duplicateIndices - a list of indexes of items that are duplicates of the current item.
  • identificationAttempts - a list of attempts in the format of (attributes, identiferName, attemptResult, searchOnTable) where
    • attributes - the attributes used during identification
    • identiferName - the CI identifier to which this identifier belongs
    • attemptResult - one of SKIPPED, NO_MATCH, MATCHED, MULTI_MATCH
    • searchOnTable - the table searched during the identification process.
The possible name-value pairs within the relations list are:
  • className - the relationship CI's class name and is always cmdb_rel_ci
  • operation - one of INSERT, UPDATE, NO_CHANGE
  • sysId - the sys_id of the relationship CI inserted or updated

Sample responses

Line feeds have been added for presentation.

{"items":[{"className":"cmdb_ci_web_server",
                                "operation":"UPDATE",
                                "sysId":"5f8af237c0a8010e01a932999468b83a",
                                "identifierEntrySysId":"8985a23ec3f00200d8d4bea192d3ae08",
                                "identificationAttempts":[{"attributes":["running_process_command",
                                                              "running_process_parameters"],
                                                              "identifierName":"Application Rule",
                                                              "attemptResult":"MATCHED","searchOnTable":"cmdb_ci_appl"}]},
                    {"className":"cmdb_ci_linux_server",
                                 "operation":"UPDATE",
                                 "sysId":"53958ff0c0a801640171ec76aa0c8f86",
                                 "identifierEntrySysId":"556eb250c3400200d8d4bea192d3ae92",
                                 "identificationAttempts":[{"attributes":["serial_number"],
                                                              "identifierName":"Hardware Rule",
                                                               "attemptResult":"SKIPPED","searchOnTable":"cmdb_ci_hardware"},
                                                           {"attributes":["name"],"identifierName":"Hardware Rule",
                                                             "attemptResult":"MATCHED","searchOnTable":"cmdb_ci_hardware"}]}],
"relations":[{"className":"cmdb_rel_ci","operation":"UPDATE","sysId":"60bcdcebc0a8010e0124fb16964b989f"}]}

Status codes

Table 4. Status codes
Status code Description
200 Indicates the request completed successfully.