IdentificationEngineScriptableApi - createOrUpdateCI( String source, String input)

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

Table 1. Parameters
Name Type Description
source String Identifies the data source of the CI information. These must be one of the choice values defined for the discovery_source field of the cmdb_ci table.
input 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 - the sys_class_name of the CI to be created or updated.
  • values:{} - the field information for the CI as name-value pairs, where the name is the field name. When updating reference fields, the value must be the referenced sys_id.
  • lookup:[{}] - a list of records with each item having name-value pairs like the items list.
The possible name-value pairs within the relations list are:
  • parent - index of the parent item in the dependency relation
  • child - index of the child item in the dependency relation
  • type - the relationship type. This is one of the name field values from the cmdb_rel_type table.
Table 2. Returns
Type Description
String A JSON formatted string that is a list of results for the configuration items in the input string. Each result string is in the format  'items: [{}], relations:[{}]', where each item within the items and relations lists contains name-value pairs.
The possible name-value pairs within the items list are:
  • className- the sys_class_name for the CI that was updated or created.
  • operation, which is one of INSERT, UPDATE, UPDATE_WITH_UPGRADE, UPDATE_WITH_DOWNGRADE, UPDATE_WITH_SWITCH, DELETE, NO_CHANGE
  • sysId - the sys_id of the CI that was updated or created.
  • relatedSysIds - a list of sys_id values of CIs used during lookup based identification.
  • identifierEntrySysId - sys_id of identifier entry used during matching.
  • errors - a list of errors in the format of (error, message string), where error can be ABANDONED, INVALID_INPUT_DATA, IDENTIFICATION_RULE_MISSING, IDENTIFICATION_RULE_FOR_LOOKUP_MISSING, NO_LOOKUP_RULES_FOR_DEPENDENT_CI, NO_CLASS_NAME_FOR_INDEPENDENT_CI, MISSING_DEPENDENCY, MULTIPLE_DEPENDENCIES, MULTIPLE_DUPLICATE_RECORDS, RELATION_CHAIN_ENDS_AT_QUALIFIER, QUALIFICATION_LOOP, TYPE_CONFLICT_IN_QUALIFICATION, MULTI_MATCH, REQUIRED_ATTRIBUTE_EMPTY, RECLASSIFICATION_NOT_ALLOWED
  • duplicateIndices - a list of indexes of items that are duplicates of the current item.
  • identificationAttempts - a list of attempts in the format of (attributes, identiferName, attemptResult, searchOnTable) where
    • attributes - the attributes of identifier entry used during identification
    • identiferName - the CI identifier to which this identifier entry belongs
    • attemptResult - one of SKIPPED, NO_MATCH, MATCHED, MULTI_MATCH
    • searchOnTable - the table searched during the identification process.
The possible name-value pairs within the relations list are:
  • className - the relationship CI's class name and is always cmdb_rel_ci
  • operation - one of INSERT, UPDATE, NO_CHANGE
  • sysId - the sys_id of the relationship CI inserted or updated

Identify an independent CI.

var payload = {items: [{className:'cmdb_ci_linux_server', 
               values: {name:'stry0900844 CI 2',
                        serial_number:'9876EFGH',
                        mac_address:'4653XYZ',
                        ip_address:'10.10.10.4',
                        ram:'1238'}}]
              };

var jsonUntil = new JSON();
var input = jsonUntil.encode(payload);
var output = SNC.IdentificationEngineScriptableApi.createOrUpdateCI('ServiceNow', input);
gs.print(output);

Output:

{"items":[{"className":"cmdb_ci_linux_server","operation":"INSERT",
"sysId":"33dd7e760f750200293f8fbce1050ee0","identifierEntrySysId":"Unknown",
"identificationAttempts":[{"attributes":["serial_number"],"identifierName":"Hardware Rule",
"attemptResult":"NO_MATCH","searchOnTable":"cmdb_ci_hardware"},{"attributes":["name"],
"identifierName":"Hardware Rule","attemptResult":"NO_MATCH","searchOnTable":"cmdb_ci_hardware"}]}
],"relations":[]}

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 jsonUntil = new JSON();
var input = jsonUntil.encode(payload);
var output = SNC.IdentificationEngineScriptableApi.createOrUpdateCI('ServiceWatch', input);
gs.print(output);

Output: line breaks have been added for presentation.

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

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 jsonUntil = new JSON();
var input = jsonUntil.encode(payload);
var output = SNC.IdentificationEngineScriptableApi.createOrUpdateCI('ServiceNow', input);
gs.print(output);

Output: line breaks have been added for presentation.

{"items":[{"className":"cmdb_ci_netgear","operation":"UPDATE","sysId":"55b35562c0a8010e01cff22378e0aea9",
                                "relatedSysIds":["c9d5d426538202007c949096a11c0829","0dd5d426538202007c949096a11c0829"],
                                "identifierEntrySysId":"c12f9be8c3400200d8d4bea192d3aea6",
                                "identificationAttempts":[{"attributes":["serial_number","serial_number_type"],
                                                           "identifierName":"Hardware Rule","attemptResult":"MATCHED",
                                "searchOnTable":"cmdb_serial_number"}]}],
          "relations":[]}