The IdentificationEngine API uses the Identification and Reconciliation framework to minimize the creation of duplicate configuration items (CIs) and to reconcile CI attributes by only accepting information from authorized data sources when updating the Configuration Management Database (CMDB).

When using this class in a scoped application, use the sn_cmdb namespace identifier.

IdentificationEngine - createOrUpdateCI(String source, String input)

Inserts or updates configuration items (CI) and non-Configuration Management Database (CMDB) CIs (classes not extending from cmdb_ci) in the CMDB based on identification and reconciliation rules. Use this API instead of updating the CMDB directly.

For additional information on non-CMDB table ingestion, see IRE support for non-CMDB tables.

Table 2. Returns
TypeDescription
<String> 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.

Data type: String
<String>.additionalCommittedItems No values are currently returned.
<String>.additionalCommittedRelations No values are currently returned.
<String>.items List of objects that describe the created or updated CIs.

Data type: Array

"items": { 
  "additionalRelatedItems": [Array],
  "className": "String",
  "duplicateIndices": [Array],
  "errorCount": Number,
  "errors": [Array],
  "identificationAttempts": [Array],
  "identifierEntrySysId": "String",
  "info": [Array],
  "inputIndices": [Array],
  "maskedAttributes": [Array],
  "operation": "String",
  "relatedItems": [Array],
  "relatedSysIds": [Array],
  "sysId": "String"
}
<String>.items.additionalRelatedItems List of JSON objects that provides information about additional lookup and related items that were processed but not provided as part of the input payload. These items are from partial payloads.

This information is not currently returned.

Data type: Array

"additionalRelatedItems": [ 
  {
    "className": "String", 
    "inputIndices": [Array], 
    "operation": "String",
    "sysId": "String"
  }
]
<String>.items.additionalRelatedItems.className Class/table name (sys_class_name) of the CI that was created or updated.

Data type: String
<String>.items.additionalRelatedItems.inputIndices Index of the corresponding input item. For top-level items, it is a list of integers. For related or lookup items, it is list of JSON objects.

Data type: Array of Numbers or Array of objects

"inputIndices": [
  { 
   "mainIndex": Number, 
   "subIndex": Number 
  }
]
<String>.items.additionalRelatedItems.inputIndices.mainIndex Index value from the request body items array that corresponds to the CI parent of the additional related item.

Data type: Number
<String>.items.additionalRelatedItems.inputIndices.subIndex Index value from the request body items.lookup array that corresponds to the additional related item.

Data type: Number
<String>.items.additionalRelatedItems.operation Type of operation.

Possible values:

  • INSERT: New CI was inserted into the database.
  • NO_CHANGE: No CI changes were made.
  • UPDATE: Existing CI was updated.

Data type: String
<String>.items.additionalRelatedItems.sysId Sys_id of the additional related items.

Data type: String
<String>.items.className Class/table name (sys_class_name) of the CI that was created or updated.

Data type: String
<String>.items.duplicateIndices List of indexes of CIs that are duplicates of the current item.

Data type: Array
<String>.items.errorCount Number of errors.

Data type: Number
<String>.items.errors Array of objects in which each object describes an error encountered while processing this CI.

Data type: Array

"errors": [
  {
    "error": "String",
    "message": "String"
  }
]
<String>.items.errors.error Type of error encountered while processing the CI.

Data type: String
<String>.items.errors.message Error message associated with the error.

Data type: String
<String>.items.identificationAttempts List of attempts that were made to identify the CIs.

Data type: Array

"identificationAttempts": [
  { 
    "attemptResult": "String", 
    "attributes": [Array],
    "hybridEntryCiAttributes": [Array],
    "identifierName": "String",
    "searchOnTable": "String" 
  }
]
<String>.items.identificationAttempts.attemptResult Results of the attempt to identify the CI.

Possible values:

  • MATCHED: Identification succeeded. A unique CI was found in the identifier rule table which exactly matched the specified attributes.
  • MULTI_MATCH: Identification failed with an error. Duplicate CIs were found in the identifier rule table when matching against the specified attributes.
  • NO_MATCH: Identification failed. No CI was found in the identifier rule table which matched the specified attributes.
  • SKIPPED: Identification not attempted. The attributes required for this identifier rule table search were not provided, so the rule was not applied.

Data type: String
<String>.items.identificationAttempts.attributes List of CI identifier entry attributes that were used during the identification process.

Data type: Array

Attribute names and types depend on the request body data and the identifier in use, such as:

"attributes": [
  "serial_number": "String",
  "serial_number_type": "String",
]
<String>.items.identificationAttempts.hybridEntryCiAttributes No values are currently returned.
<String>.items.identificationAttempts.identifierName Identifier rule used for this CI identification attempt.

Data type: String
<String>.items.identificationAttempts.searchOnTable Name of the table searched during the identification process.

Data type: String
<String>.items.identifierEntrySysId Sys_id for the identifier rule used to identify the CI. Located in the Identifier Entry [cmdb_identifier_entry] table.

Data type: String
<String>.items.info List of objects that contain additional information about the processing of the item.

Data type: Array

"info": [
  {
    "code": "String",
    "message": "String",
    "ruleSysId": "String"
  }
]
<String>.items.info.code Reclassification type that was skipped.
Possible values:
  • SKIPPED_CLASS_SWITCH
  • SKIPPED_CLASS_DOWNGRADE
  • SKIPPED_CLASS_UPGRADE

Data type: String
<String>.items.info.message Message that provides additional insights into the reason for skipping the reclassification.

Data type: String
<String>.items.info.ruleSysId Sys_id of the reclassification restriction rule that was matched. Applicable only when IRE skips reclassification due to reclassification restriction rule. This value is empty if the reclassification is skipped due to a payload or global flag.

Data type: String
<String>.items.inputIndices Index values for CIs from the request body items array that correspond to this CI.

Data type: Array
<String>.items.maskedAttributes List of attributes whose update by a non-authoritative data source was skipped as defined by the Reconciliation Rules.

Data type: Array
<String>.items.relatedItems List of JSON objects that provides information about the processed related items.

Data type: Array

"relatedItems": [
  { 
    "className": "String",
    "errors": [Array],
    "errorCount": Number, 
    "inputIndices": [Array],
    "operation": "String",
    "sysId": "String"
  }
]
<String>.items.relatedItems.className Class/table name (sys_class_name) of the related item.

Data type: String
<String>.items.relatedItems.errors List of errors that occurred during processing.

Data type: Array

"errors": [
  {
    "error": "String",
    "message": "String"
  }
]
<String>.items.relatedItems.errorCount Number of errors detected during processing.

Data type: Number
<String>.items.relatedItems.inputIndices Indexes of the corresponding related items.

Data type: Array or Numbers

"inputIndices": [
  { 
   "mainIndex": Number, 
   "subIndex": Number 
  }
]
<String>.items.relatedItems.inputIndices.mainIndex Integer value from the request body items array that corresponds to the CI parent of the related item.

Data type: Number
<String>.items.relatedItems.inputIndices.subIndex Integer value from the request body items.lookup array that corresponds to the related item.

Data type: Number
<String>.items.relatedItems.operation Type of operation.

Possible values:

  • INSERT: New CI was inserted into the database.
  • NO_CHANGE: No CI changes were made.
  • UPDATE: Existing CI was updated.

Data type: String
<String>.items.relatedSysIds List of the sys_id values for related items (table lookup items) from the request body items.lookup array.

Notable values - null: No sys_id was identified for this related item.

Data type: Array
<String>.items.sys_id Sys_id of the CI that was updated or created.

Data type: String
<String>.relations List of JSON objects that provides information about the processed relations.

Data type: Array

"relations":[
  { 
    "className": "String",
    "errorCount": Number,
    "inputIndices": [Array],
    "operation": "String",
    "sysId": "String" 
  }
]
<String>.relations.className Sys_class_name of this dependent relationship CI.

Only supported value: cmdb_rel_ci: CI Relationship table.

Data type: String
<String>.relations.errorCount Number of errors.

Data type: Number
<String>.relations.inputIndices Indexes of the corresponding input relations.

Data type: Array
<String>.relations.operation Type of operation performed.

Possible values:

  • INSERT
  • UPDATE
  • NO_CHANGE

Data type: String
<String>.relations.sysId Sys_id of the dependent relationship CI.

Data type: String

Example

The following shows how to reclassify a configuration item.

var payload = {
  "items": [
    {
      "className": "cmdb_ci_win_server",
      "values": {
        "short_description": "Linux server description",
        "name": "Linux Server 1"
      }
    }
  ]
};

var input = JSON.stringify(payload);
var output = sn_cmdb.IdentificationEngine.createOrUpdateCI('ServiceNow', input);

gs.info(JSON.stringify(JSON.parse(output), null, 2));

Output:

{
  "items": [
    {
      "className": "cmdb_ci_linux_server",
      "operation": "NO_CHANGE",
      "sysId": "440577800f321010150efc91ff767e94",
      "identifierEntrySysId": "556eb250c3400200d8d4bea192d3ae92",
      "identificationAttempts": [
        {
          "attributes": [],
          "info": "sys_object_source SKIPPED",
          "identifierName": "",
          "attemptResult": "SKIPPED",
          "hybridEntryCiAttributes": []
        },
        {
          "attributes": [
            "serial_number",
            "serial_number_type"
          ],
          "identifierName": "Hardware Rule",
          "attemptResult": "SKIPPED",
          "searchOnTable": "cmdb_serial_number",
          "hybridEntryCiAttributes": []
        },
        {
          "attributes": [
            "serial_number"
          ],
          "identifierName": "Hardware Rule",
          "attemptResult": "SKIPPED",
          "searchOnTable": "cmdb_ci_hardware",
          "hybridEntryCiAttributes": []
        },
        {
          "attributes": [
            "name"
          ],
          "identifierName": "Hardware Rule",
          "attemptResult": "MATCHED",
          "searchOnTable": "cmdb_ci_hardware",
          "hybridEntryCiAttributes": []
        }
      ],
      "info": [
        {
          "message": "CI Reclassification not allowed from class: [cmdb_ci_linux_server] to [cmdb_ci_win_server] by a reclassification restriction rule",
          "code": "SKIPPED_CLASS_SWITCH",
          "ruleSysId": "b3d4b3800f321010150efc91ff767eab"
        }
      ],
      "errorCount": 0,
      "warningCount": 0,
      "markers": [],
      "inputIndices": [
        0
      ],
      "mergedPayloadIds": []
    }
  ],
  "additionalCommittedItems": [],
  "relations": [],
  "additionalCommittedRelations": []
}

Example

The following shows how to update a configuration item.

var payload = {
"items": [
{
 "className": "cmdb_ci_win_server", 
 "values": {
   "chassis_type": "Desktop",
   "os": "Windows 2012 R2 Datacenter",
   "name": "Windows2012Server1",
   "serial_number": "0000-0011-1690-8730-8636-5722-52",
   "cpu_count": "1"
  },
  "lookup": [
  {
     "values": {
       "valid": "true",
       "serial_number": "0000-0011-1690-8730-8636-5722-52",
       "serial_number_type": "bios"
      },
     "className": "cmdb_serial_number"
   },
   {
     "values": {
       "valid": "true",
       "serial_number": "3311-9736-4988-9744-1749-4183-41",
       "serial_number_type": "chassis"
      },
     "className": "cmdb_serial_number"
   }],

    "internal_id": "16777219",
    "sys_object_source_info": {
      "source_feed": "SN Discovery Feed 1",
      "source_name": "ServiceNow",
      "source_native_key": "16777219",
      "source_recency_timestamp": "2019-10-18 08:31:23"
   }},
   {  
   "className": "cmdb_ci_spkg",
   "values": {
     "name": "Windows 2012 R2 Datacenter",
     "key": "Microsoft Windows Server 2012 R2 Datacenter_:::_NULL"
     },

  "related": [
    {
      "internal_id": "Microsoft Windows Server 2012 R2 Datacenter_:::_NULL|16777219",
      "values": {
        "name": "Windows 2012 R2 Datacenter-SAMLABVM52"
      },
      "className": "cmdb_software_instance",
      "sys_object_source_info": {
        "source_feed": "SN Discovery Feed 1",
        "source_name": "ServiceNow",
        "source_native_key": "Microsoft Windows Server 2012 R2 Datacenter_:::_NULL|16777219"
  }}]}, 
  {
  "className": "cmdb_ci_app_server_tomcat",
  "values": {
    "running_process_key_parameters": "/opt/OV/nonOV/tomcat/b/temp org.apache.catalina.startup.Bootstrap start",
    "install_directory": "/opt/OV/nonOV/tomcat/b",
    "name": "Tomcat@hpom9:3443",
    "server_port": "8006",
    "sys_class_name": "cmdb_ci_app_server_tomcat"
  },

  "internal_id": "tomcat_id"
  }],

"relations": [
  {
    "parent_id": "tomcat_id",
    "child_id": "16777219",
    "type": "Runs on::Runs"
  }],

"referenceItems": [
  {
    "referenceField": "installed_on",
    "referenced": "16777219",
    "referencedBy": "Microsoft Windows Server 2012 R2 Datacenter_:::_NULL|16777219"
  }]};

var input = JSON.stringify(payload);
var output = sn_cmdb.IdentificationEngine.createOrUpdateCI('ServiceNow', input);

gs.info(JSON.stringify(JSON.parse(output), null, 2));

Output:

{
  "items": [
    {
      "className": "cmdb_ci_win_server",
      "operation": "INSERT",
      "sysId": "d56ab6eadbd510102f67dfea5e96194e",
      "relatedSysIds": [
        "dd6af62adb1910102f67dfea5e96197f",
        "996af62adb1910102f67dfea5e961980"
      ],
      "relatedItems": [
        {
          "errors": [],
          "operation": "INSERT",
          "errorCount": 0,
          "mergedPayloadIds": [],
          "warningCount": 0,
          "sysId": "dd6af62adb1910102f67dfea5e96197f",
          "markers": [],
          "inputIndices": [
            {
              "mainIndex": 0,
              "subIndex": 0
            }
          ],
          "className": "cmdb_serial_number"
        },
        {
          "errors": [],
          "operation": "INSERT",
          "errorCount": 0,
          "mergedPayloadIds": [],
          "warningCount": 0,
          "sysId": "996af62adb1910102f67dfea5e961980",
          "markers": [],
          "inputIndices": [
            {
              "mainIndex": 0,
              "subIndex": 1
            }
          ],
          "className": "cmdb_serial_number"
        }
      ],
      "identifierEntrySysId": "Unknown",
      "identificationAttempts": [
        {
          "info": "sys_object_source NO_MATCH",
          "identifierName": "",
          "attemptResult": "NO_MATCH",
          "attributes": [],
          "hybridEntryCiAttributes": []
        },
        {
          "identifierName": "Hardware Rule",
          "attemptResult": "NO_MATCH",
          "attributes": [
            "serial_number",
            "serial_number_type"
          ],
          "searchOnTable": "cmdb_serial_number",
          "hybridEntryCiAttributes": []
        },
        {
          "identifierName": "Hardware Rule",
          "attemptResult": "NO_MATCH",
          "attributes": [
            "serial_number"
          ],
          "searchOnTable": "cmdb_ci_hardware",
          "hybridEntryCiAttributes": []
        },
        {
          "identifierName": "Hardware Rule",
          "attemptResult": "NO_MATCH",
          "attributes": [
            "name"
          ],
          "searchOnTable": "cmdb_ci_hardware",
          "hybridEntryCiAttributes": []
        },
        {
          "identifierName": "Hardware Rule",
          "attemptResult": "SKIPPED",
          "attributes": [
            "mac_address",
            "name"
          ],
          "searchOnTable": "cmdb_ci_network_adapter",
          "hybridEntryCiAttributes": []
        }
      ],
      "errorCount": 0,
      "mergedPayloadIds": [],
      "warningCount": 0,
      "markers": [],
      "inputIndices": [
        0
      ]
    },
    {
      "className": "cmdb_ci_spkg",
      "operation": "INSERT",
      "sysId": "116af62adb1910102f67dfea5e961981",
      "relatedSysIds": [
        "6d6af62adb1910102f67dfea5e961984"
      ],
      "relatedItems": [
        {
          "errors": [],
          "operation": "INSERT",
          "errorCount": 0,
          "mergedPayloadIds": [],
          "warningCount": 0,
          "sysId": "6d6af62adb1910102f67dfea5e961984",
          "markers": [],
          "inputIndices": [
            {
              "mainIndex": 1,
              "subIndex": 0
            }
          ],
          "className": "cmdb_software_instance"
        }
      ],
      "identifierEntrySysId": "Unknown",
      "identificationAttempts": [
        {
          "info": "sys_object_source SKIPPED",
          "identifierName": "",
          "attemptResult": "SKIPPED",
          "attributes": [],
          "hybridEntryCiAttributes": []
        },
        {
          "identifierName": "Software",
          "attemptResult": "NO_MATCH",
          "attributes": [
            "key"
          ],
          "searchOnTable": "cmdb_ci_spkg",
          "hybridEntryCiAttributes": []
        }
      ],
      "errorCount": 0,
      "mergedPayloadIds": [],
      "warningCount": 0,
      "markers": [],
      "inputIndices": [
        1
      ]
    },
    {
      "className": "cmdb_ci_app_server_tomcat",
      "operation": "INSERT",
      "sysId": "e96af62adb1910102f67dfea5e961985",
      "identifierEntrySysId": "Unknown",
      "identificationAttempts": [
        {
          "info": "sys_object_source SKIPPED",
          "identifierName": "",
          "attemptResult": "SKIPPED",
          "attributes": [],
          "hybridEntryCiAttributes": []
        }
      ],
      "errorCount": 0,
      "mergedPayloadIds": [],
      "warningCount": 0,
      "markers": [],
      "inputIndices": [
        2
      ]
    }
  ],
  "additionalCommittedItems": [],
  "relations": [
    {
      "className": "cmdb_rel_ci",
      "operation": "INSERT",
      "sysId": "e96af62adb1910102f67dfea5e961989",
      "identifierEntrySysId": "Unknown",
      "errorCount": 0,
      "mergedPayloadIds": [],
      "warningCount": 0,
      "markers": [],
      "inputIndices": [
        0
      ]
    }
  ],
  "additionalCommittedRelations": []
}

Example

Identify a dependent CI.

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

var input = JSON.stringify(payload);
var output = sn_cmdb.IdentificationEngine.createOrUpdateCI('ServiceNow', input);

gs.info(JSON.stringify(JSON.parse(output), null, 2));

Output:

{
  "items": [
    {
      "className": "cmdb_ci_web_server",
      "operation": "INSERT",
      "sysId": "b9bb766adb1910102f67dfea5e961962",
      "identifierEntrySysId": "Unknown",
      "identificationAttempts": [
        {
          "info": "sys_object_source SKIPPED",
          "identifierName": "",
          "attemptResult": "SKIPPED",
          "attributes": [],
          "hybridEntryCiAttributes": []
        },
        {
          "info": "sys_object_source SKIPPED",
          "identifierName": "",
          "attemptResult": "SKIPPED",
          "attributes": [],
          "hybridEntryCiAttributes": []
        }
      ],
      "errorCount": 0,
      "mergedPayloadIds": [],
      "warningCount": 0,
      "markers": [],
      "inputIndices": [
        0
      ]
    },
    {
      "className": "cmdb_ci_linux_server",
      "operation": "INSERT",
      "sysId": "a5bb766adb1910102f67dfea5e96195b",
      "identifierEntrySysId": "Unknown",
      "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": "SKIPPED",
          "attributes": [
            "serial_number"
          ],
          "searchOnTable": "cmdb_ci_hardware",
          "hybridEntryCiAttributes": []
        },
        {
          "identifierName": "Hardware Rule",
          "attemptResult": "NO_MATCH",
          "attributes": [
            "name"
          ],
          "searchOnTable": "cmdb_ci_hardware",
          "hybridEntryCiAttributes": []
        },
        {
          "identifierName": "Hardware Rule",
          "attemptResult": "SKIPPED",
          "attributes": [
            "mac_address",
            "name"
          ],
          "searchOnTable": "cmdb_ci_network_adapter",
          "hybridEntryCiAttributes": []
        }
      ],
      "errorCount": 0,
      "mergedPayloadIds": [],
      "warningCount": 0,
      "markers": [],
      "inputIndices": [
        1
      ]
    }
  ],
  "additionalCommittedItems": [],
  "relations": [
    {
      "className": "cmdb_rel_ci",
      "operation": "INSERT",
      "sysId": "fdbb766adb1910102f67dfea5e961964",
      "identifierEntrySysId": "Unknown",
      "errorCount": 0,
      "mergedPayloadIds": [],
      "warningCount": 0,
      "markers": [],
      "inputIndices": [
        0
      ]
    }
  ],
  "additionalCommittedRelations": []
}

Example

Identify an independent CI with lookup-based identification.

var payload = {items: [
           {className:'cmdb_ci_netgear', 
               values: {name:'ny8500-nbxs08',
                        ports:'1200'}, 
               lookup: [{className:'cmdb_serial_number',
                            values:{serial_number:'1234ABCD', serial_number_type:'uuid',absent:'false',valid:'true'}},
                        {className:'cmdb_serial_number',
                            values:{serial_number:'3456EFGH', serial_number_type:'system',absent:'false',valid:'true'}}]}]};

var input = JSON.stringify(payload);
var output = sn_cmdb.IdentificationEngine.createOrUpdateCI('ServiceNow', input);

gs.info(JSON.stringify(JSON.parse(output), null, 2));

Output:

{
  "items": [
    {
      "className": "cmdb_ci_netgear",
      "operation": "INSERT",
      "sysId": "787c7e6adb1910102f67dfea5e96196e",
      "relatedSysIds": [
        "f47c7e6adb1910102f67dfea5e961977",
        "3c7c7e6adb1910102f67dfea5e961977"
      ],
      "relatedItems": [
        {
          "errors": [],
          "operation": "INSERT",
          "errorCount": 0,
          "mergedPayloadIds": [],
          "warningCount": 0,
          "sysId": "f47c7e6adb1910102f67dfea5e961977",
          "markers": [],
          "inputIndices": [
            {
              "mainIndex": 0,
              "subIndex": 0
            }
          ],
          "className": "cmdb_serial_number"
        },
        {
          "errors": [],
          "operation": "INSERT",
          "errorCount": 0,
          "mergedPayloadIds": [],
          "warningCount": 0,
          "sysId": "3c7c7e6adb1910102f67dfea5e961977",
          "markers": [],
          "inputIndices": [
            {
              "mainIndex": 0,
              "subIndex": 1
            }
          ],
          "className": "cmdb_serial_number"
        }
      ],
      "identifierEntrySysId": "Unknown",
      "identificationAttempts": [
        {
          "info": "sys_object_source SKIPPED",
          "identifierName": "",
          "attemptResult": "SKIPPED",
          "attributes": [],
          "hybridEntryCiAttributes": []
        },
        {
          "identifierName": "Hardware Rule",
          "attemptResult": "NO_MATCH",
          "attributes": [
            "serial_number",
            "serial_number_type"
          ],
          "searchOnTable": "cmdb_serial_number",
          "hybridEntryCiAttributes": []
        },
        {
          "identifierName": "Hardware Rule",
          "attemptResult": "SKIPPED",
          "attributes": [
            "serial_number"
          ],
          "searchOnTable": "cmdb_ci_hardware",
          "hybridEntryCiAttributes": []
        },
        {
          "identifierName": "Hardware Rule",
          "attemptResult": "NO_MATCH",
          "attributes": [
            "name"
          ],
          "searchOnTable": "cmdb_ci_hardware",
          "hybridEntryCiAttributes": []
        },
        {
          "identifierName": "Hardware Rule",
          "attemptResult": "SKIPPED",
          "attributes": [
            "mac_address",
            "name"
          ],
          "searchOnTable": "cmdb_ci_network_adapter",
          "hybridEntryCiAttributes": []
        }
      ],
      "errorCount": 0,
      "mergedPayloadIds": [],
      "warningCount": 0,
      "markers": [],
      "inputIndices": [
        0
      ]
    }
  ],
  "additionalCommittedItems": [],
  "relations": [],
  "additionalCommittedRelations": []
}

IdentificationEngine - createOrUpdateCIEnhanced(String source, String input, Object options)

Inserts or updates configuration items (CI) and non-Configuration Management Database (CMDB) CIs (classes not extending from cmdb_ci) in the CMDB based on identification and reconciliation rules. Use this API instead of updating the CMDB directly.

In addition to providing the functionality of the createOrUpdateCI() method, this method also supports:
  • Handling partial payloads
  • Handling partial commits
  • Removing duplicate items within a payload
  • Generating output summaries
For additional information on IRE and more detailed explanations of the data used by this method, see Identification and Reconciliation (IRE).

For additional information on non-CMDB table ingestion, see IRE support for non-CMDB tables.

Table 3. Parameters
NameTypeDescription
input String Required. Input payload. A JSON formatted string of configuration items to add or update. 
"input" { 
 "items": [Array],
 "referenceItems": [Array],
 "relations": [Array]
}
input.items Array Array of objects that define the items to add or update.
"items": [
  { 
    "className": "String",
    "display_values": {Object},
    "internal_id": "String",
    "lookup": [Array],
    "related": [Array],
    "settings": {Object},
    "sys_object_source_info": {Object},
    "values": {Object}
  }
]
input.items.className String Required. Class/table name, sys_class_name, of the configuration item (CI) to create or update.

This value can be any CMDB class/table, such as cmdb_ci_linux_server or cmdb_ci_win_server.
input.items.display_values Object Reference fields to create or update for this related item as name-value pairs, where the name is the field name and the value is the referenced display value. If you want to use the sys_id instead of the display value for reference fields, pass the information in the input.items.lookup.values parameter instead of in this parameter.

Reference field names depend on the fields selected by the user, such as:

"display_values": {
  "model_id": "String",
  "location": "String"
}
input.items.internal_id String Unique item identifier for the associated payload.

This can be any value, but must be unique within the payload.
input.items.lookup Array Identifies the top-level item containing the lookup (lookup-based identification). These records are used to identify the configuration item based on a lookup table that has a reference back to cmdb_ci.

For example:

"lookup": [
  {
    "className": "String",
    "internal_id": "String",
    "sys_object_source_info": {Object},
    "values": {Object}
  }
]
input.items.lookup.className String Required. Class/table name, sys_class_name, of the configuration item (CI) to create or update.

This value can be any CMDB class/table, such as cmdb_serial_number or cmdb_ci_network_adapter.
input.items.lookup.internal_id String Unique lookup item identifier for the associated payload.

This can be any value, but must be unique within the payload.
input.items.lookup.sys_object_source_info Object Defines a unique CI identifier for a specific data source. Different sources may have different name-value pairs for the same CI.
"sys_object_source_info": { 
  "source_feed": "String",
  "source_name": "String",  
  "source_native_key": "String",
  "source_recency_timestamp": "String"
}
input.items.lookup.sys_object_source_info.source_feed String If the source can have multiple feeds, use this field to provide the name of the feed sending this item.

The data source generates this feed name. It can be any string that uniquely identifies the source feed.
input.items.lookup.sys_object_source_info.source_name String Data source of the CI information. This value must be one of the choice values defined for the discovery_source field of the Configuration Item [cmdb_ci] table.
input.items.lookup.sys_object_source_info.source_native_key String Unique key-id for the item from the source.

The data source generates this key. It can be any string that is unique to the item.
input.items.lookup.sys_object_source_info.source_recency_timestamp String UTC date/time that the item was scanned.

Format: YYYY-MM-DD hh:mm:ss
input.items.lookup.values Object Field information for the CI as name-value pairs, where the name is the field name. When updating reference fields, the value must be the referenced sys_id.

Field names and types depend on the fields selected by the user, such as:

"values": {
  "serial_number": "String",
  "serial_number_type": "String",
  "valid": "String",
  "ip_address": "String",
  "mac_address": "String"
}
input.items.related Array Reference to the top-level item that contains the related list. Rules in the Related Entry [cmdb_related_entry] define what type of records can be in this array. These records are used to add items based on a related table that has a reference to the CI that is being identified.

The related table may or may not extend cmdb_ci. These records are not used to identify the configuration item.

"related" [
  {
    "className": "String",
    "internal_id": "String",
    "sys_object_source_info": {Object},
    "values": {Object}
  }
]
input.items.related.className String Required. Class/table name, sys_class_name, of the configuration item (CI) to create or update.

This value can be any CMDB class/table, such as cmdb_software_instance or cmdb_key_value.
input.items.related.internal_id String Unique identifier for this related item in this payload. Can be any value, but must be unique within the payload.
input.items.related.sys_object_source_info Object Object that makes up a unique CI identifier for a specified data source. Different sources may have different name-value pairs for the same CI.
"sys_object_source_info": { 
  "source_feed": "String",
  "source_name": "String",  
  "source_native_key": "String",
  "source_recency_timestamp": "String"
}
input.items.related.sys_object_source_info.source_feed String If the source can have multiple feeds, use this field to provide the name of the feed sending this item.

The data source generates this feed name. It can be any string that uniquely identifies the source feed.
input.items.related.sys_object_source_info.source_name String Identifies the data source of the CI information. This value must be one of the choice values defined for the discovery_source field of the Configuration Item [cmdb_ci] table.
input.items.related.sys_object_source_info.source_native_key String Unique key/ID from the source for the related item.

The data source generates this key. It can be any string that is unique to the item.
input.items.related.sys_object_source_info.source_recency_timestamp String UTC date and time that the item was scanned.

Format: YYYY-MM-DD hh:mm:ss
input.items.related.values Object Fields to create or update for this related item as name/value pairs, where the name is the field name. For a reference field, the value must be the referenced sys_id. If you want to use the display value instead of the sys_id for reference fields, pass this information in a display_values object instead of in the values object.

Field names and types depend on the fields selected by the user, such as:

"values": {
  "host_name": "String",
  "ip_address": "String",
  "name": "String",
  "os_name": "String",
  "sys_class_name": "String"
}
input.items.settings Object Parameters that define the types of updates that are permitted.
"settings": { 
  "skipReclassificationRestrictionRules": Boolean, 
  "updateWithoutDowngrade": Boolean, 
  "updateWithoutSwitch": Boolean,
  "updateWithoutUpgrade": Boolean
}
input.items.settings.skipReclassificationRestrictionRules Boolean Flag that indicates whether IRE should not run the Reclassification Restriction rule that matches the class for the payload item.
Valid values:
  • true: Skip running the rule.
  • false: Run the rule.

Default: false
input.items.settings.updateWithoutDowngrade Boolean Flag that indicates whether update and downgrade are both permitted for this item.
Valid values:
  • true: Update the item but downgrade is not permitted.
  • false: Both item update and downgrade are permitted.

Default: false
input.items.settings.updateWithoutSwitch Boolean Flag that indicates whether the item can be updated and the class switched.
Valid values:
  • true: Update the item but class switching is not permitted.
  • false: Both item update and class switching are permitted.

Default: false
input.items.settings.updateWithoutUpgrade Boolean Flag that indicates whether update and upgrade are both permitted for this item.
Valid values:
  • true: Update the item but upgrade is not permitted.
  • false: Both item update and upgrade are permitted.

Default: false
input.items.sys_object_source_info Object Unique CI identifier for a specific source.
"sys_object_source_info": { 
  "source_feed": "String",
  "source_name": "String",  
  "source_native_key": "String",
  "source_recency_timestamp": "String"
}
input.items.sys_object_source_info.source_feed String If the source can have multiple feeds, use this field to provide the name of the feed sending this item.

The data source generates this feed name. It can be any string that uniquely identifies the source feed.
input.items.sys_object_source_info.source_name String Data source of the CI information. This value must be one of the choice values defined for the discovery_source field of the Configuration Item [cmdb_ci] table.
input.items.sys_object_source_info.source_native_key String Unique key/id for the item from the source.

The data source generates this key. It can be any string that is unique to the item.
input.items.sys_object_source_info.source_recency_timestamp String UTC date and time that the item was scanned.

Format: YYYY-MM-DD hh:mm:ss
input.items.values Object Fields to create or update for this related item as name/value pairs, where the name is the field name. For a reference field, the value must be the referenced sys_id. If you want to use the display value instead of the sys_id for reference fields, pass this information in a display_values object instead of in the values object.

Field names and types depend on the fields selected by the user, such as:

"values": {
  "host_name": "String",
  "ip_address": "String",
  "name": "String",
  "os_name": "String",
  "sys_class_name": "String"
}
input.referenceItems Array Array of objects that define references between items in the input payload. 
"referenceItems": [
  { 
    "referenced": "String", 
    "referencedBy": "String", 
    "referenceField": "String" 
  }
]
input.referenceItems.referenced String The internal_id defined for the item being referenced by another item.
input.referenceItems.referencedBy String The internal_id defined for the item that references another item.
input.referenceItems.referenceField String Name of the reference field in the class/table for the referencedBy item.
input.relations Array Array of objects that specify relationships between items in the input payload.
An object in this array can use either of two formats.
  • The object can define a relationship between two top-level items (only) using parent and child name-value pairs, with values representing item indexes from the payload items array.
    "relations": [
  {
    "child": Number,
    "parent": Number,
    "sys_rel_source_info": {Object},
    "type": "String"
  }
]
  • The object can define a relationship between any two items, including top-level, related, or lookup items, using parent_id and child_id key/value pairs, with values representing internal_id values defined for those items.
    "relations": [
  {
    "child_id": "String",
    "parent_id": "String",
    "sys_rel_source_info": {Object},
    "type": "String"
  }
]
input.relations.child Number Integer index of the CI object in the items array that represents the child in the relationship (items, items.related, or items.lookup.)
input.relations.child_id String The internal_id of the child item in the relation (items, items.related, or items.lookup.)
input.relations.parent Number Integer index of the parent item in the items array (items, items.related, or items.lookup.)
input.relations.parent_id String The internal_id of the parent item in the relation (items, items.related, or items.lookup.)
input.relations.sys_rel_source_info Object Discovery source information for the relationship. For non-dependency relationships, this information is saved in the Relationship Sources [sys_rel_source] table (not persisted for identifyCIEnhanced() or identifyCI() methods.)

Data type: Object

"sys_rel_source_info": { 
  "source_name": "String", 
  "source_feed": "String" 
}
input.relations.sys_rel_source_info.source_name String Discovery source name.

Default: Discovery source passed in the API method parameter.
input.relations.sys_rel_source_info.source_feed String Any string that is a sub-discovery/scan within the discovery source.

Default: 'UNKNOWN' is stored in the source_feed column when creating a record in sys_rel_source table.
input.relations.type String Type of relationship that exists between the parent and child items. This must be a name field value from the CI Relationship Type [cmdb_rel_type] table.
options Object Optional, but {} or null must be passed-in. Options to enable or disable features.
Note: By default or if partial_payloads is set to true, both partial_commits and deduplicate_payloads are enabled, even if they are set to false, as those features are essential for partial payloads functionality.
"options": { 
 "deduplicate_payloads": "Boolean",
 "generate_summary": "Boolean", 
 "partial_commits": "Boolean", 
 "partial_payloads": "Boolean",
 "skip_updating_last_scan_to_now": "Boolean",
 "skip_updating_source_last_discovered_to_now": "Boolean"
}
options.deduplicate_payloads Boolean Flag that indicates whether duplicate items are merged or considered errors.

Valid values:

  • true: Merge duplicate items.
  • false: Consider duplicate items as errors.

Default: true
options.generate_summary Boolean Flag that indicates whether the returned results contain summary information. For the details of the returned summary information, see <String>.summary in the return results table.

Valid values:

  • true: Include summary information.
  • false: Do not include summary information.

Default: false
options.partial_commits Boolean Flag that indicates whether partial commit support is enabled. For additional information on partial commits, see Enhanced IRE features.

Valid values:

  • true: Partial commit enabled.
  • false: Partial commit disabled.

Default: true
options.partial_payloads Boolean Flag that indicates whether partial payload support is enabled. For additional information on partial payloads, see Enhanced IRE features and Create an IRE data source rule.

Valid values:

  • true: Partial payload enabled.
  • false: Partial payload disabled.

Default: true
options.skip_updating_last_scan_to_now Boolean Flag that indicates whether to skip updating the sys_object_source's last_scan time field.
Valid values:
  • true: If the source_recency_timestamp parameter is not passed in sys_object_source_info, do not update the sys_object_source's last_scan time field.
  • false: Update the sys_object_source's last_scan time field.

Default: Uses the value in the glide.identification_engine.skip_updating_last_scan_to_now system property.
options.skip_updating_source_last_discovered_to_now Boolean Flag that indicates whether to skip updating the discovery_source and last_discovered fields in the Configuration Item [cmdb_ci] table.
Valid values:
  • true: If last_discovered is not provided in the payload item values, do not update the discovery_source and last_discovered fields.
  • false: Update the discovery_source and last_discovered fields.

Default: Uses the value in the glide.identification_engine.skip_updating_source_last_discovered_to_now system property.
source String Data source of the CI information. This value must be one of the choice values defined for the discovery_source field of the Configuration Item [cmdb_ci] table.
Table 4. Returns
ParameterDescription
<String> JSON formatted string that is a list of results for the configuration items in the input string.

Data type: String

{ 
  "additionalCommittedItems": [Array],  
  "additionalCommittedRelations": [Array], 
  "hasError": "Boolean", 
  "hasWarning": "Boolean",
  "items": [Array],  
  "relations": [Array], 
  "summary": {Object} 
}
<String>.additionalCommittedItems List of CIs that were committed during the IRE processing of the current payload, but were not present in the current input payload.

Data type: Array

"additionalCommittedItems": [
  {
    "className": "String",
    "errorCount": Number,
    "operation": "String",
    "identificationAttempts": [Array],
    "inputIndices": [Array],
    "markers": [Array],
    "mergedPayloads": [Array],
    "sysId": "String"
  }
]
<String>.additionalCommittedItems.className Sys_class_name of this additional CI.

Data type: String
<String>.additionalCommittedItems.errorCount Number of errors encountered while processing this additional CI.

Data type: Number
<String>.additionalCommittedItems.errors Array of objects that describes errors encountered while processing this additional CI.

Data type: Array

"errors": [
  {
    "error": "String",
    "message": "String"
  }
]
<String>.additionalCommittedItems.errors.error Type of error encountered while processing the additional CI.

Data type: String
<String>.additionalCommittedItems.errors.message Error message encountered while processing the additional CI.

Data type: String
<String>.additionalCommittedItems.identificationAttempts Array of objects in which each object describes an attempt made to identify this additional CI.
Data type: Array
"identificationAttempts": [
  {
    "attemptResult": "String",
    "attributes": [Array],
    "hybridEntryCiAttributes": [Array],
    "identiferName": "String",
    "searchOnTable": [Array]
  }
]
<String>.additionalCommittedItems.identificationAttempts.attemptResult Outcome of this additional CI identification attempt.

Data type: String

Possible values:
  • MATCHED: Identification succeeded. A unique CI was found in the identifier rule table which exactly matched the specified attributes.
  • MULTI_MATCH: Identification failed with an error. Duplicate CIs were found in the identifier rule table when matching against the specified attributes.
  • NO_MATCH: Identification failed. No CI was found in the identifier rule table which matched the specified attributes.
  • SKIPPED: Identification not attempted. The attributes required for this identifier rule table search were not provided, so the rule was not applied.
<String>.additionalCommittedItems.identificationAttempts.attributes Array of CI identifier entry attributes used during this additional CI identification attempt.

Data type: Array

Attribute names and types depend on the request body data and the identifier in use, such as:

"attributes": [
  "serial_number": "String",
  "serial_number_type": "String",
]
<String>.additionalCommittedItems.identificationAttempts.hybridEntryCiAttributes Array of CI identifier entry attributes used during this additional CI identification attempt.

Data type: Array

Attribute names and types depend on the request body data and the identifier in use, such as:

"hybridEntryCiAttributes": [
  "name": "String",
  "serial_number": "String"
]
<String>.additionalCommittedItems.identificationAttempts.identifierName Identifier rule used for this additional CI identification attempt.

Data type: String
<String>.additionalCommittedItems.identificationAttempts.searchOnTable Name of the table searched for this additional CI identification attempt.

Data type: String
<String>.additionalCommittedItems.identifierEntrySysId Sys_id for the identifier rule used to identify this additional CI.

Notable values - Unknown: Identification of this additional CI failed. See errors for details.
<String>.additionalCommittedItems.inputIndices Array of index values for CIs from the request body items array that correspond to this additional CI.

Data type: Array

"inputIndices": [
  {
    Number
  }
]
<String>.additionalCommittedItems.markers Array of marker values for internal use.

Data type: Array

"markers": []
<String>.additionalCommittedItems.mergedPayloads Array of sys_id values for partial payloads from the CMDB IRE Partial Payloads [cmdb_ire_partial_payloads] table that were merged during processing of this additional CI.

Data type: Array

"mergedPayloadIds": [
  "String"
]
<String>.additionalCommittedItems.operation Operation performed for this additional CI.

Data type: String

Possible values:
  • DELETE: An existing CI is removed from the target table.
  • INSERT: The additional CI is inserted into the target table as a new record.
  • NO_CHANGE: No operation is performed for the additional CI.
  • UPDATE: An existing CI in the target table is updated.
  • UPDATE_WITH_DOWNGRADE: An existing CI in the target table is updated and its class is changed to a more generic class (ancestor class).
  • UPDATE_WITH_SWITCH: An existing CI in the target table is updated and its class is changed to another class which is not an ancestor or descendent class.
  • UPDATE_WITH_UPGRADE: An existing CI in the target table is updated and its class is changed to a more specialized class (descendent class).
<String>.additionalCommittedItems.sysId Sys_id found for this additional CI through identification.

Data type: String

Notable values - Unknown: Identification of this additional CI failed. See errors for details.
<String>.additionalCommittedItems.warnings Array of objects that describe a warning encountered while processing this additional CI.

Data type: Array

"warnings": [
  {
    "error": "String",
    "message": "String"
  }
]
<String>.additionalCommittedItems.warnings.error Type of warning encountered while processing this additional CI.

Data type: String
<String>.additionalCommittedItems.warnings.message Warning message encountered while processing this additional CI.

Data type: String
<String>.additionalCommittedRelations Array of objects that describe a dependent relationship CI that was not included in the request body relations list to insert or update.

Data type: Array

"additionalCommittedRelations": [
  {
    "className": "String",
    "inputIndices": [Array],
    "markers": [Array],
    "mergedPayloadIds": [Array],
    "operation": "String"
  }
]
<String>.additionalCommittedRelations.className The sys_class_name of this additional dependent relationship CI.

Data type: String

Only supported value: cmdb_rel_ci: The CI Relationship table.
<String>.additionalCommittedRelations.errorCount Number of errors encountered while processing this additional dependent relationship CI.

Data type: Number
<String>.additionalCommittedRelations.errors Array of objects that describe errors encountered while processing this additional dependent relationship CI.

Data type: Array

"errors": [
  {
    "error": "String",
    "message": "String"
  }
]
<String>.additionalCommittedRelations.errors.error Type of error encountered while processing the additional dependent relationship CI.

Data type: String
<String>.additionalCommittedRelations.errors.message The error message encountered while processing this additional dependent relationship CI.

Data type: String
<String>.additionalCommittedRelations.inputIndices Index values for dependent relationship CI objects in the request body relations array that correspond to this additional dependent relationship CI.

Data type: Array

"inputIndices": [
  Number
]
<String>.additionalCommittedRelations.markers Marker values for internal use.

Data type: Array

"markers": []
<String>.additionalCommittedRelations.mergedPayloadIds Sys_id values for partial payloads from the CMDB IRE Partial Payloads [cmdb_ire_partial_payloads] table that were merged for this CI.that were merged during processing of this additional dependent relationship CI.

Data type: Array

"mergedPayloadIds": [
  "String"
]
<String>.additionalCommittedRelations.operation Operation that was performed for the additional dependent relationship CI.
Possible values:
  • INSERT: The dependent relationship CI is inserted into the target table as a new record.
  • INSERT_AS_INCOMPLETE: The dependent relationship CI had errors and is inserted into the CMDB IRE Incomplete Payloads [cmdb_ire_incomplete_payloads] table.
  • INSERT_AS_PARTIAL: The dependent relationship CI had errors and is inserted into the CMDB IRE Partial Payloads [cmdb_ire_partial_payloads] table.
  • NO_CHANGE: No operation is performed for the dependent relationship CI.
  • UPDATE: An existing dependent relationship CI in the target table is updated.

Data type: String
<String>.hasError Flag that indicates whether any item or relation has errors.

Data type: Boolean
<String>.hasWarning Flag that indicates whether any item or relation has warnings.

Data type: Boolean
<String>.items Array of objects that describe the created or updated CIs.

Data type: Array

"items": [
  {  
    "additionalRelatedItems": [Array],
    "className": "String",
    "duplicateIndices": [Array],
    "errorCount": Number, 
    "errors": [Array], 
    "identificationAttempts": [Array], 
    "identifierEntrySysId": "String",  
    "incompleteSysIds": "String",
    "info": [Array],
    "inputIndices": [Array], 
    "maskedAttributes": [Array],
    "operation": "String", 
    "partialSysIds": "String", 
    "relatedItems": [Array], 
    "relatedSysIds": [Array], 
    "sysId": "String" 
  }
]
<String>.items.additionalRelatedItems List of JSON objects that provide information about additional lookup and related items that were processed but not provided as part of the input payload. These items are from partial payloads.

Data type: Array

"additionalRelatedItems": [ 
  {
    "className": "String", 
    "inputIndices": [Array],
    "mergedPayloadIds": [Array], 
    "operation": "String",
    "sysId": "String"
  }
]
<String>.items.additionalRelatedItems.className Class/table name (sys_class_name) of the CI that was created or updated.

Data type: String
<String>.items.additionalRelatedItems.inputIndices Index values for CIs from the request body items array that correspond to this related item.

Data type: Array of Numbers
<String>.items.additionalRelatedItems.mergedPayloadIds List of sys_ids of the partial payloads that were merged into the related item. Located in the CMDB IRE Partial Payloads [cmdb_ire_partial_payloads] table.

Data type: Array
<String>.items.additionalRelatedItems.operation Type of operation.

Possible values:

  • INSERT: New CI was inserted into the database.
  • NO_CHANGE: No CI changes were made.
  • UPDATE: Existing CI was updated.

Data type: String
<String>.items.additionalRelatedItems.sysId Sys_id of the CI that was updated or created.

Data type: String
<String>.items.className Class/table name (sys_class_name) of the CI that was created or updated.

Data type: String
<String>.items.duplicateIndices List of indexes of CIs that are duplicates of the current item.

Data type: Array
<String>.items.errorCount Number of errors encountered while processing the item.

Data type: Number
<String>.items.errors Array of objects in which each object describes an error encountered while processing this CI.

Data type: Array

"errors": [
  {
    "error": "String",
    "message": "String"
  }
]
<String>.items.errors.error Type of error encountered while processing the CI.

Data type: String
<String>.items.errors.message Error message associated with the error.

Data type: String
<String>.items.identificationAttempts List of attempts that were made to identify the CIs.

Data type: Array

"identificationAttempts": [
  { 
    "attemptResult": "String", 
    "attributes": [Array],
    "hybridEntryCiAttributes": [Array],
    "identifierName": "String",
    "searchOnTable": "String" 
  }
]
<String>.items.identificationAttempts.attemptResult Results of the attempt to identify the CI.

Possible values:

  • MATCHED: Identification succeeded. A unique CI was found in the identifier rule table which exactly matched the specified attributes.
  • MULTI_MATCH: Identification failed with an error. Duplicate CIs were found in the identifier rule table when matching against the specified attributes.
  • NO_MATCH: Identification failed. No CI was found in the identifier rule table which matched the specified attributes.
  • SKIPPED: Identification not attempted. The attributes required for this identifier rule table search were not provided, so the rule was not applied.

Data type: String
<String>.items.identificationAttempts.attributes List of CI identifier entry attributes that were used during the identification process.

Data type: Array

Attribute names and types depend on the request body data and the identifier in use, such as:

"attributes": [
  "serial_number": "String",
  "serial_number_type": "String",
]
<String>items.identificationAttempts.hybridEntryCiAttributes List of CI identifier entry attributes that were used during the identification process.

Data type: Array

Attribute names and types depend on the request body data and the identifier in use, such as:

"hybridEntryCiAttributes": [
  "name": "String",
  "serial_number": "String"
]
<String>.items.identificationAttempts.identifierName Identifier rule used for this CI identification attempt.

Data type: String
<String>.items.identificationAttempts.searchOnTable Name of the table searched during the identification process.

Data type: String
<String>.items.identifierEntrySysId Sys_id for the identifier rule used to identify the CI. Located in the Identifier Entry [cmdb_identifier_entry] table.

Data type: String
<String>.items.incompleteSysIds If the item had errors and was saved as an incomplete payload, this parameter contains the sys_id of the record in the CMDB IRE Incomplete Payloads [cmdb_ire_incomplete_payloads] table.

Data type: String
<String>.items.info List of objects that contains additional information about the processing of the item.

Data type: Array

"info": [
  {
    "code": "String",
    "message": "String",
    "ruleSysId": "String"
  }
]
<String>.items.info.code Reclassification type that was skipped.
Possible values:
  • SKIPPED_CLASS_SWITCH
  • SKIPPED_CLASS_DOWNGRADE
  • SKIPPED_CLASS_UPGRADE

Data type: String
<String>.items.info.message Message that provides additional insights into the reason for skipping the reclassification.

Data type: String
<String>.items.info.ruleSysId Sys_id of the reclassification restriction rule that was matched. Applicable only when IRE skips reclassification due to reclassification restriction rule. This value is empty if the reclassification is skipped due to a payload or global flag.

Data type: String
<String>.items.inputIndices Indexes of the corresponding input CI. For top-level items, it is a list of integers. For related or lookup CIs, it is list of JSON objects.

Data type: Array of Numbers
<String>.items.maskedAttributes List of attributes whose update by a non-authoritative data source was skipped as defined by the Reconciliation Rules.

Data type: Array
<String>.items.operation Operation that took place.

Possible values:

  • INSERT: New CI was inserted into the database.
  • INSERT_AS_INCOMPLETE: Item was saved in cmdb_ire_incomplete_payloads table.
  • INSERT_AS_PARTIAL: Item was saved in cmdb_ire_partial_payloads table.
  • UPDATE: Existing CI was updated.
  • UPDATE_WITH_DOWNGRADE: CI was updated and the class changed to a more generic class (ancestor class).
  • UPDATE_WITH_SWITCH: CI was updated and the class changed to a class that is not ancestor or descendent.
  • UPDATE_WITH_UPDRADE: CI was updated and the class changed to a more specialized class (descendent class).

Data type: String
<String>.items.partialSysIds If the item had errors and was saved as a partial payload, this parameter contains the sys_id of the partial payload record.

Data type: String
<String>.items.relatedItems List of JSON objects that describes a related CI (table lookup CI) from the request body items.lookup array.

Data type: Array

"relatedItems": [
  { 
    "className": "String",
    "errors": [Array],
    "errorCount": Number, 
    "incompleteSysIds": [Array],
    "inputIndices": [Array],
    "mergePayloadIds": [Array],
    "operation": "String",
    "partialSysIds": [Array], 
    "sysId": "String",
    "warningCount": Number,
    "warnings": [Array]
  }
]
<String>.items.relatedItems.className Class/table name (sys_class_name) of the related item.

Data type: String
<String>.items.relatedItems.errors List of errors that occurred during processing of the related item.

Data type: Array

"errors": [
  {
    "error": "String",
    "message": "String"
  }
]
<String>.items.relatedItems.errors.error Type of error encountered while processing the related item.

Data type: String
<String>.items.relatedItems.errors.message Error message associated with the error.

Data type: String
<String>.items.relatedItems.errorCount Number of errors detected while processing the related items.

Data type: Number
<String>.items.relatedItems.incompleteSysIds If the relation had errors and was saved as an incomplete payload, this value is the sys_id of the record in the CMDB IRE Incomplete Payloads [cmdb_ire_incomplete_payloads] table.

Data type: String
<String>.items.relatedItems.inputIndices Index of the corresponding input item. For top-level items, it is a list of integers. For related or lookup items, it is list of JSON objects.

Data type: Array of Numbers or Array of Objects

"inputIndices": [
  { 
   "mainIndex": Number, 
   "subIndex": Number 
  }
]
<String>.items.relatedItems.inputIndices.mainIndex Index value from the request body items array that corresponds to the CI parent of the related item.

Data type: Number
<String>.items.relatedItems.inputIndices.subIndex Index value from the request body items.lookup array that corresponds to the related item.

Data type: Number
<String>.items.relatedItems.mergedPayloadIds List of sys_ids of the partial payloads that were merged into the CI during processing.

Data type: Array
<String>.items.relatedItems.operation Operation that took place.

Possible values:

  • INSERT: New related CI was inserted into the database.
  • INSERT_AS_INCOMPLETE: Item was saved in cmdb_ire_incomplete_payloads table.
  • INSERT_AS_PARTIAL: Item was saved in cmdb_ire_partial_payloads table.
  • NO_CHANGE: No related CI changes were made.
  • UPDATE: Existing related CI was updated.
  • UPDATE_WITH_DOWNGRADE: Related CI was updated and the class changed to a more generic class (ancestor class).
  • UPDATE_WITH_SWITCH: Related CI was updated and the class changed to a class that is not ancestor or descendent.
  • UPDATE_WITH_UPDRADE: Related CI was updated and the class changed to a more specialized class (descendent class).

Data type: String
<String>.items.relatedItems.partialSysIds If the related item had errors and was saved as a partial payload, this contains a list of the sys_ids of the associated records in the CMDB IRE Partial Payloads [cmdb_ire_partial_payloads] table.

Data type: Array
<String>.items.relatedItems.sysId The sys_id of the related item.

Data type: String
<String>.items.relatedItems.warningCount Number of warnings encountered when processing the related items.

Data type: Number
<String>.items.relatedItems.warnings Array of objects that describes a warning encountered while processing the related items.

Data type: Array

"warnings": [
  {
    "error": "String",
    "message": "String"
  }
]
<String>.items.relatedItems.warnings.error Type of warning encountered while processing the related item.

Data type: String
<String>.items.relatedItems.warnings.message Message associated with the warning.

Data type: String
<String>.items.relatedSysIds List of the sys_id values of the CIs used during lookup-based identification of related items.

Data type: String
<String>.items.sys_id Sys_id of the CI that was updated or created.

Data type: String
<String>.relations List of JSON objects that describe a dependent relationship CI from the request body relations array.

Data type: Array

"relations": [ 
  { 
    "className": "String",
    "errorCount": Number,
    "errors": [Array],
    "incompleteSysIds": "String",
    "inputIndices": [Array],
    "operation": "String",
    "partialSysIds": "String",
    "sysId": "String" 
  }
]
<String>.relations.className Sys_class_name of this dependent relationship CI.

Only supported value: cmdb_rel_ci: CI Relationship table.

Data type: String
<String>.relations.errorCount Number of errors encountered when processing the dependent relationship CI.

Data type: Number
<String>.relations.errors Array of objects that describe errors that were encountered while processing this dependent relationship CI.

Data type: Array

"errors": [
  {
    "error": "String",
    "message": "String"
  }
]
<String>.relations.errors.error Type of error encountered while processing the dependent relationship CI.

Data type: String
<String>.relations.errors.message Error message encountered while processing this dependent relationship CI.

Data type: String
<String>.relations.incompleteSysIds If the relation had errors and was saved as an incomplete payload, this value is the sys_id of the record in the CMDB IRE Incomplete Payloads [cmdb_ire_incomplete_payloads] table.

Data type: String
<String>.relations.inputIndices Indexes for the dependent relationship CI objects in the request body relations array that correspond to this dependent relationship CI.

Data type: Array
<String>.relations.operation Type of operation performed.

Possible values:

  • INSERT: The dependent relationship CI was inserted into the target table as a new record.
  • INSERT_AS_INCOMPLETE: The dependent relationship CI had errors and was inserted into the CMDB IRE Incomplete Payloads [cmdb_ire_incomplete_payloads] table.
  • INSERT_AS_PARTIAL: The dependent relationship CI had errors and was inserted into the CMDB IRE Partial Payloads [cmdb_ire_partial_payloads] table.
  • NO_CHANGE: No operation was performed.
  • UPDATE: An existing dependent relationship CI in the target table was updated.

Data type: String
<String>.relations.partialSysIds If the relation had errors and was saved as a partial payload, this value is the sys_id of the record in the CMDB IRE Partial Payloads [cmdb_ire_partial_payloads] table.

Data type: String
<String>.relations.sysId Sys_id of the dependent relationship CI.

Data type: String
<String>.summary List of JSON properties that provide statistics on how many items were inserted, updated, and such, per class.

Data type: Array
<String>.summary.<class_name> Statistics for a specific class.

Data type: Object

<class_name>: {
 "additionalInsertedItemCount": Number, 
 "errorCount": Number,
 "incompleteItemCount": Number,
 "insertedItemCount": Number,
 "partialItemCount": Number,
 "skippedItemCount": Number,
 "unchangedItemCount": Number,
 "updatedItemCount": Number,
 "warningCount": Number 
}
<String>.summary.<class_name>.additionalInsertedItemCount Number of items inserted due to processing of partial payloads.

Data type: Number
<String>.summary.<class_name>.errorCount Number of errors encounter when processing items.

Data type: Number
<String>.summary.<class_name>.incompleteItemCount Number of items inserted in the CMDB IRE Incomplete Payloads [cmdb_ire_incomplete_payloads] table.

Data type: Number
<String>.summary.<class_name>.insertedItemCount Number of items created.

Data type: Number
<String>.summary.<class_name>.partialItemCount Number of items saved in the Partial Payload table [cmdb_ire_partial_payloads].

Data type: Number
<String>.summary.<class_name>.skippedItemCount Number of items that were skipped.

Data type: Number
<String>.summary.<class_name>.unchangedItemCount Number of items that had entries but were not modified.

Data type: Number
<String>.summary.<class_name>.updatedItemCount Number of items updated.

Data type: Number
<String>.summary.<class_name>.warningCount Number of items that generated a warning when processed.

Data type: Number

Example

This example shows how to import multiple CI entries.

var payload = {
"items": [
{
 "className": "cmdb_ci_win_server", 
 "values": {
   "chassis_type": "Desktop",
   "os": "Windows 2012 R2 Datacenter",
   "name": "Windows2012Server1",
   "serial_number": "0000-0011-1690-8730-8636-5722-52",
   "cpu_count": "1"
  },
  "lookup": [
  {
     "values": {
       "valid": "true",
       "serial_number": "0000-0011-1690-8730-8636-5722-52",
       "serial_number_type": "bios"
      },
     "className": "cmdb_serial_number"
   },
   {
     "values": {
       "valid": "true",
       "serial_number": "3311-9736-4988-9744-1749-4183-41",
       "serial_number_type": "chassis"
      },
     "className": "cmdb_serial_number"
   }],

    "internal_id": "16777219",
    "sys_object_source_info": {
      "source_feed": "SN Discovery Feed 1",
      "source_name": "ServiceNow",
      "source_native_key": "16777219",
      "source_recency_timestamp": "2019-10-18 08:31:23"
   }},
   {  
   "className": "cmdb_ci_spkg",
   "values": {
     "name": "Windows 2012 R2 Datacenter",
     "key": "Microsoft Windows Server 2012 R2 Datacenter_:::_NULL"
     },

  "related": [
    {
      "internal_id": "Microsoft Windows Server 2012 R2 Datacenter_:::_NULL|16777219",
      "values": {
        "name": "Windows 2012 R2 Datacenter-SAMLABVM52"
      },
      "className": "cmdb_software_instance",
      "sys_object_source_info": {
        "source_feed": "SN Discovery Feed 1",
        "source_name": "ServiceNow",
        "source_native_key": "Microsoft Windows Server 2012 R2 Datacenter_:::_NULL|16777219"
  }}], 
  "settings" : {
        "skipReclassificationRestrictionRules" : "false",
        "updateWithoutDowngrade" : "true",
        "updateWithoutUpgrade" : "true",
        "updateWithoutSwitch" : "true"
      }}, 
  {
  "className": "cmdb_ci_app_server_tomcat",
  "values": {
    "running_process_key_parameters": "/opt/OV/nonOV/tomcat/b/temp org.apache.catalina.startup.Bootstrap start",
    "install_directory": "/opt/OV/nonOV/tomcat/b",
    "name": "Tomcat@hpom9:3443",
    "server_port": "8006",
    "sys_class_name": "cmdb_ci_app_server_tomcat"
  },

  "internal_id": "tomcat_id"
  }],

"relations": [
  {
    "parent_id": "tomcat_id",
    "child_id": "16777219",
    "type": "Runs on::Runs"
  }],

"referenceItems": [
  {
    "referenceField": "installed_on",
    "referenced": "16777219",
    "referencedBy": "Microsoft Windows Server 2012 R2 Datacenter_:::_NULL|16777219"
  }]};

var input = JSON.stringify((payload));
var output = sn_cmdb.IdentificationEngine.createOrUpdateCIEnhanced('ServiceNow', input, {});

gs.info(JSON.stringify(JSON.parse(output), null, 2));

Output:

{

"items": [
{
  "className": "cmdb_ci_win_server",
  "operation": "NO_CHANGE",
  "sysId": "65d873d2b3a0001028f6eae2c6a8dc2a",
  "relatedSysIds": [
    "a1d873d2b3a0001028f6eae2c6a8dc32",
    "a1d873d2b3a0001028f6eae2c6a8dc33"
],

"relatedItems": [
{
  "className": "cmdb_serial_number",
  "sysId": "a1d873d2b3a0001028f6eae2c6a8dc32",
  "markers": [],
  "inputIndices": [
  {
    "mainIndex": 0,
    "subIndex": 0
  }]
},
  "className": "cmdb_serial_number",
  "sysId": "a1d873d2b3a0001028f6eae2c6a8dc33",
  "markers": [],
  "inputIndices": [
  {
    "mainIndex": 0,
    "subIndex": 1
  }]
}],

"additionalRelatedItems": [],
"identificationAttempts": [],
"errorCount": 0,
"inputIndices": [0]
},
{
"className": "cmdb_ci_spkg",
"operation": "NO_CHANGE",
"sysId": "c764e971b320001028f6eae2c6a8dc44",

"relatedSysIds": [
  "8b64e971b320001028f6eae2c6a8dc47"
],
"relatedItems": [
  {
  "className": "cmdb_software_instance",
  "sysId": "8b64e971b320001028f6eae2c6a8dc47",
  "markers": [],
  "inputIndices": [
    {
      "mainIndex": 1,
      "subIndex": 0
    }]
  }],

"additionalRelatedItems": [],
"identifierEntrySysId": "a52a87c03746220006b216a543990e8c",
"identificationAttempts": [
  {
    "attributes": [
      "key"
     ],
    "identifierName": "Software",
    "attemptResult": "MATCHED",
    "searchOnTable": "cmdb_ci_spkg",
    "hybridEntryCiAttributes": []
  }],

"errorCount": 0,
"inputIndices": [1]
},

{
"className": "cmdb_ci_app_server_tomcat",
"operation": "INSERT",
"sysId": "6f29f3d2b3a0001028f6eae2c6a8dcc6",
"identifierEntrySysId": "Unknown",
"identificationAttempts": [
{
  "attributes": [
    "install_directory",
    "running_process_key_parameters",
    "sys_class_name"
  ],
"identifierName": "Tomcat",
"attemptResult": "NO_MATCH",
"searchOnTable": "cmdb_ci_app_server_tomcat",
"hybridEntryCiAttributes": []
},
{
"attributes": [
  "cl_port",
  "sys_class_name"
],
"identifierName": "Application Rule",
"attemptResult": "SKIPPED",
"searchOnTable": "cmdb_ci_appl",
"hybridEntryCiAttributes": []
},
{
"attributes": [
  "running_process_command",
  "running_process_key_parameters",
  "sys_class_name"
],
"identifierName": "Application Rule",
"attemptResult": "NO_MATCH",
"searchOnTable": "cmdb_ci_appl",
"hybridEntryCiAttributes": []
}
],

"errorCount": 0,
"inputIndices": [2]
}
],
"additionalCommittedItems": [],
"relations": [
{
  "className": "cmdb_rel_ci",
  "operation": "INSERT",
  "sysId": "6729f3d2b3a0001028f6eae2c6a8dcc9",
  "errorCount": 0,
  "inputIndices": [0]
}],
"additionalCommittedRelations": []
}

IdentificationEngine - identifyCI(String jsonString)

Determines the operation (insert/update) to perform with the specified payload without committing the operation in the database.

This works just like createOrUpdateCI(), but does not commit the result.

Table 5. Parameters
Name Type Description
jsonString String 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 - Sys_class_name of the CI to be created or updated.
  • values:{} - Field information for the CI as name-value pairs, where the name is the field name.
  • lookup:[{}] - 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 - Relationship type. This is one of the name field values from the cmdb_rel_type table.
Table 6. Returns
Type Description
String A JSON formatted string that is a list of results. 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 - Sys_class_name for the CI that was updated or created.
  • operation - Operation to perform, which is one of the following:
    • DELETE
    • INSERT
    • UPDATE
    • UPDATE_WITH_DOWNGRADE
    • UPDATE_WITH_SWITCH
    • UPDATE_WITH_UPGRADE
  • sysId - Sys_id of the CI that was updated or created.
  • relatedSysIds - List of sys_id values of CIs used during lookup based identification.
  • identifierEntrySysId - Sys_id of identifier entry used during matching.
  • errors - List of errors in the format of (error, message string)
  • duplicateIndices - List of indexes of items that are duplicates of the current item.
  • identificationAttempts - List of attempts in the format of (attributes, identiferName, attemptResult, searchOnTable) where
    • attributes - Attributes of identifier entry used during identification
    • identiferName - CI identifier to which this identifier entry belongs
    • attemptResult - One of SKIPPED, NO_MATCH, MATCHED, MULTI_MATCH
    • searchOnTable - Table searched during the identification process.
The possible name-value pairs within the relations list are:
  • className - Relationship CI's class name and is always cmdb_rel_ci
  • operation - Type of operation: INSERT, UPDATE, NO_CHANGE
  • sysId - Sys_id of the relationship CI inserted or updated

Example

The following shows how to reclassify a configuration item.

var payload = {
  "items": [
    {
      "className": "cmdb_ci_win_server",
      "values": {
        "short_description": "Linux server description",
        "name": "Linux Server 1"
      }
    }
  ]
};

var input = JSON.stringify(payload);
var output = sn_cmdb.IdentificationEngine.identifyCI(input);

gs.info(JSON.stringify(JSON.parse(output), null, 2));

Output:

{
  "items": [
    {
      "className": "cmdb_ci_linux_server",
      "operation": "NO_CHANGE",
      "sysId": "440577800f321010150efc91ff767e94",
      "identifierEntrySysId": "556eb250c3400200d8d4bea192d3ae92",
      "identificationAttempts": [
        {
          "attributes": [],
          "info": "sys_object_source SKIPPED",
          "identifierName": "",
          "attemptResult": "SKIPPED",
          "hybridEntryCiAttributes": []
        },
        {
          "attributes": [
            "serial_number",
            "serial_number_type"
          ],
          "identifierName": "Hardware Rule",
          "attemptResult": "SKIPPED",
          "searchOnTable": "cmdb_serial_number",
          "hybridEntryCiAttributes": []
        },
        {
          "attributes": [
            "serial_number"
          ],
          "identifierName": "Hardware Rule",
          "attemptResult": "SKIPPED",
          "searchOnTable": "cmdb_ci_hardware",
          "hybridEntryCiAttributes": []
        },
        {
          "attributes": [
            "name"
          ],
          "identifierName": "Hardware Rule",
          "attemptResult": "MATCHED",
          "searchOnTable": "cmdb_ci_hardware",
          "hybridEntryCiAttributes": []
        }
      ],
      "info": [
        {
          "message": "CI Reclassification not allowed from class: [cmdb_ci_linux_server] to [cmdb_ci_win_server] by a reclassification restriction rule",
          "code": "SKIPPED_CLASS_SWITCH",
          "ruleSysId": "b3d4b3800f321010150efc91ff767eab"
        }
      ],
      "errorCount": 0,
      "warningCount": 0,
      "markers": [],
      "inputIndices": [
        0
      ],
      "mergedPayloadIds": []
    }
  ],
  "additionalCommittedItems": [],
  "relations": [],
  "additionalCommittedRelations": []
}

IdentificationEngine - identifyCIEnhanced(String source, String input, Object options)

Determines the Configuration Management Database (CMDB) operation (insert/update) to perform with the specified payload (request body), without committing the operations in the database.

Use this method to simulate submission of a payload.

This method is similar to the IdentificationEngine - identifyCI(String jsonString) method, however it also supports the following functionality:
  • Partial payloads
    • In case of an item having a warning or error, indicates if an item operation is INSERT_AS_PARTIAL or INSERT_INCOMPLETE.
    • Returns the sys_ids of partial payloads that were merged with existing partial payloads.
  • Supports payload deduplicate feature.
  • Generates a summary.
Table 7. Parameters
NameTypeDescription
input String Required. Input payload. A JSON formatted string of configuration items to add or update. 
"input" { 
 "items": [Array],
 "referenceItems": [Array],
 "relations": [Array]
}
input.items Array Array of objects that define the items to add or update.
"items": [
  { 
    "className": "String",
    "display_values": {Object},
    "internal_id": "String",
    "lookup": [Array],
    "related": [Array],
    "settings": {Object},
    "sys_object_source_info": {Object},
    "values": {Object}
  }
]
input.items.className String Required. Class/table name, sys_class_name, of the configuration item (CI) to create or update.

This value can be any CMDB class/table, such as cmdb_ci_linux_server or cmdb_ci_win_server.
input.items.display_values Object Reference fields to create or update for this related item as name-value pairs, where the name is the field name and the value is the referenced display value. If you want to use the sys_id instead of the display value for reference fields, pass the information in the input.items.lookup.values parameter instead of in this parameter.

Reference field names depend on the fields selected by the user, such as:

"display_values": {
  "model_id": "String",
  "location": "String"
}
input.items.internal_id String Unique item identifier for the associated payload.

This can be any value, but must be unique within the payload.
input.items.lookup Array Identifies the top-level item containing the lookup (lookup-based identification). These records are used to identify the configuration item based on a lookup table that has a reference back to cmdb_ci.

For example:

"lookup": [
  {
    "className": "String",
    "internal_id": "String",
    "sys_object_source_info": {Object},
    "values": {Object}
  }
]
input.items.lookup.className String Required. Class/table name, sys_class_name, of the configuration item (CI) to create or update.

This value can be any CMDB class/table, such as cmdb_serial_number or cmdb_ci_network_adapter.
input.items.lookup.internal_id String Unique lookup item identifier for the associated payload.

This can be any value, but must be unique within the payload.
input.items.lookup.sys_object_source_info Object Defines a unique CI identifier for a specific data source. Different sources may have different name-value pairs for the same CI.
"sys_object_source_info": { 
  "source_feed": "String",
  "source_name": "String",  
  "source_native_key": "String",
  "source_recency_timestamp": "String"
}
input.items.lookup.sys_object_source_info.source_feed String If the source can have multiple feeds, use this field to provide the name of the feed sending this item.

The data source generates this feed name. It can be any string that uniquely identifies the source feed.
input.items.lookup.sys_object_source_info.source_name String Data source of the CI information. This value must be one of the choice values defined for the discovery_source field of the Configuration Item [cmdb_ci] table.
input.items.lookup.sys_object_source_info.source_native_key String Unique key-id for the item from the source.

The data source generates this key. It can be any string that is unique to the item.
input.items.lookup.sys_object_source_info.source_recency_timestamp String UTC date/time that the item was scanned.

Format: YYYY-MM-DD hh:mm:ss
input.items.lookup.values Object Field information for the CI as name-value pairs, where the name is the field name. When updating reference fields, the value must be the referenced sys_id.

Field names and types depend on the fields selected by the user, such as:

"values": {
  "serial_number": "String",
  "serial_number_type": "String",
  "valid": "String",
  "ip_address": "String",
  "mac_address": "String"
}
input.items.related Array Reference to the top-level item that contains the related list. Rules in the Related Entry [cmdb_related_entry] define what type of records can be in this array. These records are used to add items based on a related table that has a reference to the CI that is being identified.

The related table may or may not extend cmdb_ci. These records are not used to identify the configuration item.

"related" [
  {
    "className": "String",
    "internal_id": "String",
    "sys_object_source_info": {Object},
    "values": {Object}
  }
]
input.items.related.className String Required. Class/table name, sys_class_name, of the configuration item (CI) to create or update.

This value can be any CMDB class/table, such as cmdb_software_instance or cmdb_key_value.
input.items.related.internal_id String Unique identifier for this related item in this payload. Can be any value, but must be unique within the payload.
input.items.related.sys_object_source_info Object Object that makes up a unique CI identifier for a specified data source. Different sources may have different name-value pairs for the same CI.
"sys_object_source_info": { 
  "source_feed": "String",
  "source_name": "String",  
  "source_native_key": "String",
  "source_recency_timestamp": "String"
}
input.items.related.sys_object_source_info.source_feed String If the source can have multiple feeds, use this field to provide the name of the feed sending this item.

The data source generates this feed name. It can be any string that uniquely identifies the source feed.
input.items.related.sys_object_source_info.source_name String Identifies the data source of the CI information. This value must be one of the choice values defined for the discovery_source field of the Configuration Item [cmdb_ci] table.
input.items.related.sys_object_source_info.source_native_key String Unique key/ID from the source for the related item.

The data source generates this key. It can be any string that is unique to the item.
input.items.related.sys_object_source_info.source_recency_timestamp String UTC date and time that the item was scanned.

Format: YYYY-MM-DD hh:mm:ss
input.items.related.values Object Fields to create or update for this related item as name/value pairs, where the name is the field name. For a reference field, the value must be the referenced sys_id. If you want to use the display value instead of the sys_id for reference fields, pass this information in a display_values object instead of in the values object.

Field names and types depend on the fields selected by the user, such as:

"values": {
  "host_name": "String",
  "ip_address": "String",
  "name": "String",
  "os_name": "String",
  "sys_class_name": "String"
}
input.items.settings Object Parameters that define the types of updates that are permitted.
"settings": { 
  "skipReclassificationRestrictionRules": Boolean, 
  "updateWithoutDowngrade": Boolean, 
  "updateWithoutSwitch": Boolean,
  "updateWithoutUpgrade": Boolean
}
input.items.settings.skipReclassificationRestrictionRules Boolean Flag that indicates whether IRE should not run the Reclassification Restriction rule that matches the class for the payload item.
Valid values:
  • true: Skip running the rule.
  • false: Run the rule.

Default: false
input.items.settings.updateWithoutDowngrade Boolean Flag that indicates whether update and downgrade are both permitted for this item.
Valid values:
  • true: Update the item but downgrade is not permitted.
  • false: Both item update and downgrade are permitted.

Default: false
input.items.settings.updateWithoutSwitch Boolean Flag that indicates whether the item can be updated and the class switched.
Valid values:
  • true: Update the item but class switching is not permitted.
  • false: Both item update and class switching are permitted.

Default: false
input.items.settings.updateWithoutUpgrade Boolean Flag that indicates whether update and upgrade are both permitted for this item.
Valid values:
  • true: Update the item but upgrade is not permitted.
  • false: Both item update and upgrade are permitted.

Default: false
input.items.sys_object_source_info Object Unique CI identifier for a specific source.
"sys_object_source_info": { 
  "source_feed": "String",
  "source_name": "String",  
  "source_native_key": "String",
  "source_recency_timestamp": "String"
}
input.items.sys_object_source_info.source_feed String If the source can have multiple feeds, use this field to provide the name of the feed sending this item.

The data source generates this feed name. It can be any string that uniquely identifies the source feed.
input.items.sys_object_source_info.source_name String Data source of the CI information. This value must be one of the choice values defined for the discovery_source field of the Configuration Item [cmdb_ci] table.
input.items.sys_object_source_info.source_native_key String Unique key/id for the item from the source.

The data source generates this key. It can be any string that is unique to the item.
input.items.sys_object_source_info.source_recency_timestamp String UTC date and time that the item was scanned.

Format: YYYY-MM-DD hh:mm:ss
input.items.values Object Fields to create or update for this related item as name/value pairs, where the name is the field name. For a reference field, the value must be the referenced sys_id. If you want to use the display value instead of the sys_id for reference fields, pass this information in a display_values object instead of in the values object.

Field names and types depend on the fields selected by the user, such as:

"values": {
  "host_name": "String",
  "ip_address": "String",
  "name": "String",
  "os_name": "String",
  "sys_class_name": "String"
}
input.referenceItems Array Array of objects that define references between items in the input payload. 
"referenceItems": [
  { 
    "referenced": "String", 
    "referencedBy": "String", 
    "referenceField": "String" 
  }
]
input.referenceItems.referenced String The internal_id defined for the item being referenced by another item.
input.referenceItems.referencedBy String The internal_id defined for the item that references another item.
input.referenceItems.referenceField String Name of the reference field in the class/table for the referencedBy item.
input.relations Array Array of objects that specify relationships between items in the input payload.
An object in this array can use either of two formats.
  • The object can define a relationship between two top-level items (only) using parent and child name-value pairs, with values representing item indexes from the payload items array.
    "relations": [
  {
    "child": Number,
    "parent": Number,
    "sys_rel_source_info": {Object},
    "type": "String"
  }
]
  • The object can define a relationship between any two items, including top-level, related, or lookup items, using parent_id and child_id key/value pairs, with values representing internal_id values defined for those items.
    "relations": [
  {
    "child_id": "String",
    "parent_id": "String",
    "sys_rel_source_info": {Object},
    "type": "String"
  }
]
input.relations.child Number Integer index of the CI object in the items array that represents the child in the relationship (items, items.related, or items.lookup.)
input.relations.child_id String The internal_id of the child item in the relation (items, items.related, or items.lookup.)
input.relations.parent Number Integer index of the parent item in the items array (items, items.related, or items.lookup.)
input.relations.parent_id String The internal_id of the parent item in the relation (items, items.related, or items.lookup.)
input.relations.sys_rel_source_info Object Discovery source information for the relationship. For non-dependency relationships, this information is saved in the Relationship Sources [sys_rel_source] table (not persisted for identifyCIEnhanced() or identifyCI() methods.)

Data type: Object

"sys_rel_source_info": { 
  "source_name": "String", 
  "source_feed": "String" 
}
input.relations.sys_rel_source_info.source_name String Discovery source name.

Default: Discovery source passed in the API method parameter.
input.relations.sys_rel_source_info.source_feed String Any string that is a sub-discovery/scan within the discovery source.

Default: 'UNKNOWN' is stored in the source_feed column when creating a record in sys_rel_source table.
input.relations.type String Type of relationship that exists between the parent and child items. This must be a name field value from the CI Relationship Type [cmdb_rel_type] table.
options Object Optional, but {} or null must be passed-in. Options to enable or disable features.
Note: By default or if partial_payloads is set to true, both partial_commits and deduplicate_payloads are enabled, even if they are set to false, as those features are essential for partial payloads functionality.
"options": { 
 "deduplicate_payloads": "Boolean",
 "generate_summary": "Boolean", 
 "partial_commits": "Boolean", 
 "partial_payloads": "Boolean",
 "skip_updating_last_scan_to_now": "Boolean",
 "skip_updating_source_last_discovered_to_now": "Boolean"
}
options.deduplicate_payloads Boolean Flag that indicates whether duplicate items are merged or considered errors.

Valid values:

  • true: Merge duplicate items.
  • false: Consider duplicate items as errors.

Default: true
options.generate_summary Boolean Flag that indicates whether the returned results contain summary information. For the details of the returned summary information, see <String>.summary in the return results table.

Valid values:

  • true: Include summary information.
  • false: Do not include summary information.

Default: false
options.partial_commits Boolean Flag that indicates whether partial commit support is enabled. For additional information on partial commits, see Enhanced IRE features.

Valid values:

  • true: Partial commit enabled.
  • false: Partial commit disabled.

Default: true
options.partial_payloads Boolean Flag that indicates whether partial payload support is enabled. For additional information on partial payloads, see Enhanced IRE features and Create an IRE data source rule.

Valid values:

  • true: Partial payload enabled.
  • false: Partial payload disabled.

Default: true
options.skip_updating_last_scan_to_now Boolean Flag that indicates whether to skip updating the sys_object_source's last_scan time field.
Valid values:
  • true: If the source_recency_timestamp parameter is not passed in sys_object_source_info, do not update the sys_object_source's last_scan time field.
  • false: Update the sys_object_source's last_scan time field.

Default: Uses the value in the glide.identification_engine.skip_updating_last_scan_to_now system property.
options.skip_updating_source_last_discovered_to_now Boolean Flag that indicates whether to skip updating the discovery_source and last_discovered fields in the Configuration Item [cmdb_ci] table.
Valid values:
  • true: If last_discovered is not provided in the payload item values, do not update the discovery_source and last_discovered fields.
  • false: Update the discovery_source and last_discovered fields.

Default: Uses the value in the glide.identification_engine.skip_updating_source_last_discovered_to_now system property.
source String Data source of the CI information. This value must be one of the choice values defined for the discovery_source field of the Configuration Item [cmdb_ci] table.

Example

var payload = {
"items": [
{
"className": "cmdb_ci_win_server",
"values": {
   "chassis_type": "Desktop",
   "os": "Windows 2012 R2 Datacenter",
   "name": "Windows2012Server1",
   "serial_number": "0000-0011-1690-8730-8636-5722-52",
   "cpu_count": "1"
  },
  "lookup": [
  {
     "values": {
       "valid": "true",
       "serial_number": "0000-0011-1690-8730-8636-5722-52",
       "serial_number_type": "bios"
      },
     "className": "cmdb_serial_number"
   },
   {
     "values": {
       "valid": "true",
       "serial_number": "3311-9736-4988-9744-1749-4183-41",
       "serial_number_type": "chassis"
      },
     "className": "cmdb_serial_number"
   }],
 
    "internal_id": "16777219",
    "sys_object_source_info": {
      "source_feed": "SN Discovery Feed 1",
      "source_name": "ServiceNow",
      "source_native_key": "16777219",
      "source_recency_timestamp": "2019-10-18 08:31:23"
   }},
   {
   "className": "cmdb_ci_spkg",
   "values": {
     "name": "Windows 2012 R2 Datacenter",
     "key": "Microsoft Windows Server 2012 R2 Datacenter_:::_NULL"
     },
 
  "related": [
    {
     "internal_id": "Microsoft Windows Server 2012 R2 Datacenter_:::_NULL|16777219",
      "values": {
        "name": "Windows 2012 R2 Datacenter-SAMLABVM52"
      },
      "className": "cmdb_software_instance",
      "sys_object_source_info": {
        "source_feed": "SN Discovery Feed 1",
        "source_name": "ServiceNow",
        "source_native_key": "Microsoft Windows Server 2012 R2 Datacenter_:::_NULL|16777219"
  }},
  {
    "internal_id": "Microsoft Windows Server 2012 R2 Datacenter_:::_NULL|16777229",
      "values": {
        "name": "Windows 2012 R2 Datacenter-SAMLABVM52"
      },
    "className": "cmdb_software_instance",
    "sys_object_source_info": {
      "source_feed": "SN Discovery Feed 1",
      "source_name": "ServiceNow",
      "source_native_key": "Microsoft Windows Server 2012 R2 Datacenter_:::_NULL|16777229"
  }}
],
  "settings" : {
        "skipReclassificationRestrictionRules" : "false",
        "updateWithoutDowngrade" : "true",
        "updateWithoutUpgrade" : "true",
        "updateWithoutSwitch" : "true"
      }},
  {
  "className": "cmdb_ci_app_server_tomcat",
  "values": {
    "running_process_key_parameters": "/opt/OV/nonOV/tomcat/b/temp org.apache.catalina.startup.Bootstrap start",
    "install_directory": "/opt/OV/nonOV/tomcat/b",
    "name": "Tomcat@hpom9:3443",
    "server_port": "8006",
    "sys_class_name": "cmdb_ci_app_server_tomcat"
  },
 
  "internal_id": "tomcat_id"
  }],
 
"relations": [
  {
    "parent_id": "tomcat_id",
    "child_id": "16777219",
    "type": "Runs on::Runs"
  }],
 
"referenceItems": [
  {
    "referenceField": "installed_on",
    "referenced": "16777219",
    "referencedBy": "Microsoft Windows Server 2012 R2 Datacenter_:::_NULL|16777219"
  }]};
 
var input = JSON.stringify(payload);
var output = sn_cmdb.IdentificationEngine.identifyCIEnhanced('ServiceNow', input, {});

gs.info(JSON.stringify(JSON.parse(output), null, 2));

Output:

{
  "items": [
    {
      "className": "cmdb_ci_win_server",
      "operation": "INSERT",
      "relatedSysIds": [
        null,
        null
      ],
      "relatedItems": [
        {
          "errors": [],
          "operation": "INSERT",
          "className": "cmdb_serial_number",
          "errorCount": 0,
          "markers": [],
          "inputIndices": [
            {
              "mainIndex": 0,
              "subIndex": 0
            }
          ],
          "mergedPayloadIds": [],
          "warningCount": 0
        },
        {
          "errors": [],
          "operation": "INSERT",
          "className": "cmdb_serial_number",
          "errorCount": 0,
          "markers": [],
          "inputIndices": [
            {
              "mainIndex": 0,
              "subIndex": 1
            }
          ],
          "mergedPayloadIds": [],
          "warningCount": 0
        }
      ],
      "identificationAttempts": [
        {
          "attributes": [],
          "info": "sys_object_source NO_MATCH",
          "identifierName": "",
          "attemptResult": "NO_MATCH",
          "hybridEntryCiAttributes": []
        },
        {
          "attributes": [
            "serial_number",
            "serial_number_type"
          ],
          "identifierName": "Hardware Rule",
          "attemptResult": "NO_MATCH",
          "searchOnTable": "cmdb_serial_number",
          "hybridEntryCiAttributes": []
        },
        {
          "attributes": [
            "serial_number"
          ],
          "identifierName": "Hardware Rule",
          "attemptResult": "NO_MATCH",
          "searchOnTable": "cmdb_ci_hardware",
          "hybridEntryCiAttributes": []
        },
        {
          "attributes": [
            "name"
          ],
          "identifierName": "Hardware Rule",
          "attemptResult": "NO_MATCH",
          "searchOnTable": "cmdb_ci_hardware",
          "hybridEntryCiAttributes": []
        },
        {
          "attributes": [
            "mac_address",
            "name"
          ],
          "identifierName": "Hardware Rule",
          "attemptResult": "SKIPPED",
          "searchOnTable": "cmdb_ci_network_adapter",
          "hybridEntryCiAttributes": []
        }
      ],
      "errorCount": 0,
      "markers": [],
      "inputIndices": [
        0
      ],
      "mergedPayloadIds": [],
      "warningCount": 0
    },
    {
      "className": "cmdb_ci_spkg",
      "operation": "INSERT",
      "relatedSysIds": [
        null
      ],
      "relatedItems": [
        {
          "errors": [],
          "operation": "INSERT",
          "className": "cmdb_software_instance",
          "errorCount": 0,
          "markers": [],
          "inputIndices": [
            {
              "mainIndex": 1,
              "subIndex": 0
            }
          ],
          "mergedPayloadIds": [],
          "warningCount": 0
        },
        {
          "errors": [],
          "warnings": [
            {
              "error": "MISSING_MATCHING_ATTRIBUTES",
              "message": "In payload missing minimum set of input values for criterion (matching) attributes from identify rule for table [cmdb_software_instance]. Add these input values in payload item '{\"className\":\"cmdb_software_instance\",\"values\":{},\"internal_id\":\"f7273cccec30101056cd4bb46eb4db5d\",\"sys_object_source_info\":{\"source_feed\":\"SN Discovery Feed 1\",\"source_name\":\"ServiceNow\",\"source_native_key\":\"Microsoft Windows Server 2012 R2 Datacenter_:::_NULL|16777229\"},\"settings\":{},\"sys_ire_info\":{\"ire_received_time\":\"2020-05-10 17:57:48\"}}'"
            }
          ],
          "operation": "INSERT_AS_PARTIAL",
          "className": "cmdb_software_instance",
          "errorCount": 0,
          "sysId": "Unknown",
          "markers": [],
          "inputIndices": [
            {
              "mainIndex": 1,
              "subIndex": 1
            }
          ],
          "mergedPayloadIds": [],
          "warningCount": 1
        }
      ],
      "identificationAttempts": [
        {
          "attributes": [],
          "info": "sys_object_source SKIPPED",
          "identifierName": "",
          "attemptResult": "SKIPPED",
          "hybridEntryCiAttributes": []
        },
        {
          "attributes": [
            "key"
          ],
          "identifierName": "Software",
          "attemptResult": "NO_MATCH",
          "searchOnTable": "cmdb_ci_spkg",
          "hybridEntryCiAttributes": []
        }
      ],
      "errorCount": 0,
      "markers": [],
      "inputIndices": [
        1
      ],
      "mergedPayloadIds": [],
      "warningCount": 0
    },
    {
      "className": "cmdb_ci_app_server_tomcat",
      "operation": "INSERT",
      "identificationAttempts": [
        {
          "attributes": [],
          "info": "sys_object_source SKIPPED",
          "identifierName": "",
          "attemptResult": "SKIPPED",
          "hybridEntryCiAttributes": []
        }
      ],
      "errorCount": 0,
      "markers": [],
      "inputIndices": [
        2
      ],
      "mergedPayloadIds": [],
      "warningCount": 0
    }
  ],
  "additionalCommittedItems": [],
  "relations": [
    {
      "className": "cmdb_rel_ci",
      "operation": "INSERT",
      "errorCount": 0,
      "markers": [],
      "inputIndices": [
        0
      ],
      "mergedPayloadIds": [],
      "warningCount": 0
    }
  ],
  "additionalCommittedRelations": []
} 

IdentificationEngine - runIdentificationAudit(GlideRecord now_GR)

Runs an identification audit against the specified configuration item (CI) to detect duplicates.

If duplicates are found, duplication tasks are created. Only use this method on CI types with independent identification rules.

Table 9. Parameters
Name Type Description
now_GR GlideRecord CI on which to run the audit to detect duplicates. The CI must have independent identification rules.
Table 10. Returns
Type Description
void

Example

The following example shows how to check a record in the Linux Servers [cmdb_ci_linux_server] table for duplicates.

var sysId = '<cbdb_ci_sys_id>';
var gr = new GlideRecord('cmdb_ci_linux_server');
gr.get(sysId);
sn_cmdb.IdentificationEngine.runIdentificationAudit(gr);