Skip to content
Server API reference › API reference › API implementation and reference
Release: Australia · Updated: 2026-03-12 · Official documentation · View source

CMDBTransformUtil- Global

The CMDBTransformUtil script include uses the Identification and Reconciliation (IRE) framework to minimize the creation of duplicate configuration items (CI).

The IRE framework also reconciles CI attributes by only accepting information from authorized sources when updating the CMDB in onBefore transform map scripts. You can't use this class in other scripts. For additional information on how the IRE framework operates, see CMDB Identification and Reconciliation.

Parent Topic:Server API reference

CMDBTransformUtil - CMDBTransformUtil()

Creates a CMDBTransformUtil object.

NameTypeDescription
None  
var cmdbUtil = new CMDBTransformUtil();

CMDBTransformUtil - getError()

Returns any errors generated by the previous identifyAndReconcile() or identifyAndReconcileEnhanced() method call.

Use this method in onBefore transform map scripts to obtain errors. Use the hasError() method to first detect any errors from the identifyAndReconcile() or identifyAndReconcileEnhanced() method.

NameTypeDescription
None  
TypeDescription
StringError message from identifyAndReconcile() or identifyAndReconcileEnhanced().
// Add this code to the onBefore transform map script
// Call CMDB API to do Identification and Reconciliation of the current row
var cmdbUtil = new CMDBTransformUtil();
cmdbUtil.setDataSource('ImportSet');
cmdbUtil.identifyAndReconcileEnhanced(source, map, log);
ignore = true;

if (cmdbUtil.hasError()) {
  var errorMessage = cmdbUtil.getError();
  log.error(errorMessage);
} else {
  log.info('IE Output Payload: ' + cmdbUtil.getOutputPayload());
  log.info('Imported CI: ' + cmdbUtil.getOutputRecordSysId());
}

Scoped equivalent

There is no scoped equivalent for this method.

CMDBTransformUtil - getOutputPayload()

Returns the JSON payload from the previous identifyAndReconcile() or identifyAndReconcileEnhanced() method call.

Use this method in onBefore transform map scripts.

NameTypeDescription
None  
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>.additionalCommittedItemsNo values are currently returned.
<String>.additionalCommittedRelationsNo values are currently returned.
<String>.itemsDescription of the created or updated CIs.Data type: Object 
"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.additionalRelatedItemsList of 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 of Objects 
"additionalRelatedItems": [ 
  {
    "className": "String", 
    "inputIndices": [Array], 
    "operation": "String",
    "sysId": "String"
  }
]
<String>.items.additionalRelatedItems.classNameClass/table name \(sys\_class\_name\) of the CI that was created or updated.Data type: String
<String>.items.additionalRelatedItems.inputIndicesIndex 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.mainIndexIndex 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.subIndexIndex value from the request body items.lookup array that corresponds to the additional related item.Data type: Number
<String>.items.additionalRelatedItems.operationType 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.sysIdSys\_id of the additional related items.Data type: String
<String>.items.classNameClass/table name \(sys\_class\_name\) of the CI that was created or updated.Data type: String
<String>.items.duplicateIndicesList of indexes of CIs that are duplicates of the current item.Data type: Array
<String>.items.errorCountNumber of errors.Data type: Number
<String>.items.errorsList of errors encountered while processing this CI.Data type: Array of Objects 
"errors": [
  {
    "error": "String",
    "message": "String"
  }
]
<String>.items.errors.errorType of error encountered while processing the CI.Data type: String
<String>.items.errors.messageError message associated with the error.Data type: String
<String>.items.identificationAttemptsList of attempts that were made to identify the CIs.Data type: Array of Objects 
"identificationAttempts": [
  { 
    "attemptResult": "String", 
    "attributes": [Array],
    "hybridEntryCiAttributes": [Array],
    "identifierName": "String",
    "searchOnTable": "String" 
  }
]
<String>.items.identificationAttempts.attemptResultResults 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.attributesList 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.hybridEntryCiAttributesNo values are currently returned.
<String>.items.identificationAttempts.identifierNameIdentifier rule used for this CI identification attempt.Data type: String
<String>.items.identificationAttempts.searchOnTableName of the table searched during the identification process.Data type: String
<String>.items.identifierEntrySysIdSys\_id for the identifier rule used to identify the CI.Data type: String Table: Identifier Entry \[cmdb\_identifier\_entry\]
<String>.items.infoList that contain additional information about the processing of the item.Data type: Array of Objects 
"info": [
  {
    "code": "String",
    "message": "String",
    "ruleSysId": "String"
  }
]
<String>.items.info.codeReclassification type that was skipped.Possible values: - SKIPPED\_CLASS\_SWITCH - SKIPPED\_CLASS\_DOWNGRADE - SKIPPED\_CLASS\_UPGRADE Data type: String
<String>.items.info.messageMessage that provides additional insights into the reason for skipping the reclassification.Data type: String
<String>.items.info.ruleSysIdSys\_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.inputIndicesIndex values for CIs from the request body items array that correspond to this CI.Data type: Array
<String>.items.maskedAttributesList of attributes whose update by a non-authoritative data source was skipped as defined by the Reconciliation Rules.Data type: Array
<String>.items.relatedItemsList that provides information about the processed related items.Data type: Array of Objects 
"relatedItems": [
  { 
    "className": "String",
    "errors": [Array],
    "errorCount": Number, 
    "inputIndices": [Array],
    "operation": "String",
    "sysId": "String"
  }
]
<String>.items.relatedItems.classNameClass/table name \(sys\_class\_name\) of the related item.Data type: String
<String>.items.relatedItems.errorsList of errors that occurred during processing.Data type: Array of Objects 
"errors": [
  {
    "error": "String",
    "message": "String"
  }
]
<String>.items.relatedItems.errorCountNumber of errors detected during processing.Data type: Number
<String>.items.relatedItems.inputIndicesIndexes of the corresponding related items.Data type: Array or Numbers 
"inputIndices": [
  { 
   "mainIndex": Number, 
   "subIndex": Number 
  }
]
<String>.items.relatedItems.inputIndices.mainIndexInteger value from the request body items array that corresponds to the CI parent of the related item.Data type: Number
<String>.items.relatedItems.inputIndices.subIndexInteger value from the request body items.lookup array that corresponds to the related item.Data type: Number
<String>.items.relatedItems.operationType 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\_idSys\_id of the CI that was updated or created.Data type: String
<String>.relationsInformation about the processed relations.Data type: Array of Objects 
"relations":[
  { 
    "className": "String",
    "errorCount": Number,
    "inputIndices": [Array],
    "operation": "String",
    "sysId": "String" 
  }
]
<String>.relations.classNameSys\_class\_name of this dependent relationship CI.Only supported value: cmdb\_rel\_ci: CI Relationship table. Data type: String
<String>.relations.errorCountNumber of errors.Data type: Number
<String>.relations.inputIndicesIndexes of the corresponding input relations.Data type: Array
<String>.relations.operationType of operation performed.Possible values: - INSERT - UPDATE - NO\_CHANGE Data type: String
<String>.relations.sysIdSys\_id of the dependent relationship CI.Data type: String
// Add this code to the onBefore transform map script
// Call CMDB API to do Identification and Reconciliation of the current row
var cmdbUtil = new CMDBTransformUtil();
cmdbUtil.setDataSource('ImportSet');
cmdbUtil.identifyAndReconcileEnhanced(source, map, log);
ignore = true;

if (cmdbUtil.hasError()) {
  var errorMessage = cmdbUtil.getError();
  log.error(errorMessage);
} else {
  log.info('IE Output Payload: ' + cmdbUtil.getOutputPayload());
  log.info('Imported CI: ' + cmdbUtil.getOutputRecordSysId());
}

Scoped equivalent

There is no scoped equivalent for this method.

CMDBTransformUtil - getOutputRecordSysId()

Returns the sys_id of the configuration item (CI) that was inserted or updated.

Use this method in onBefore transform map scripts.

NameTypeDescription
None  
TypeDescription
StringSys_id of the CI that was inserted or updated.
// Add this code to the onBefore transform map script
// Call CMDB API to do Identification and Reconciliation of current row
var cmdbUtil = new CMDBTransformUtil();
cmdbUtil.setDataSource('ImportSet');
cmdbUtil.identifyAndReconcileEnhanced(source, map, log);
ignore = true;

if (cmdbUtil.hasError()) {
  var errorMessage = cmdbUtil.getError();
  log.error(errorMessage);
} else {
  log.info('IE Output Payload: ' + cmdbUtil.getOutputPayload());
  log.info('Imported CI: ' + cmdbUtil.getOutputRecordSysId());
}

Scoped equivalent

There is no scoped equivalent for this method.

CMDBTransformUtil - getPayload(Object source, Object map, Object log)

Returns the JSON payload generated from the specified input.

You can then modify the payload and use the setPayload() method to store the updated payload. Once the payload is modified and stored, use identifyAndReconcile() or identifyAndReconcileEnhanced() to process the payload.

NameTypeDescription
sourceObjectGlobal object available in transform map scripts that holds the incoming record.
mapObjectMap object available in transform map scripts that holds the current transform map record.
logObjectLog object available in transform map scripts.
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>.additionalCommittedItemsList 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 of Objects 
"additionalCommittedItems": [
  {
    "className": "String",
    "errorCount": Number,
    "operation": "String",
    "identificationAttempts": [Array],
    "inputIndices": [Array],
    "markers": [Array],
    "mergedPayloads": [Array],
    "sysId": "String"
  }
]
<String>.additionalCommittedItems.classNameSys\_class\_name of this additional CI.Data type: String
<String>.additionalCommittedItems.errorCountNumber of errors encountered while processing this additional CI.Data type: Number
<String>.additionalCommittedItems.errorsArray of objects that describes errors encountered while processing this additional CI.Data type: Array 
"errors": [
  {
    "error": "String",
    "message": "String"
  }
]
<String>.additionalCommittedItems.errors.errorType of error encountered while processing the additional CI.Data type: String
<String>.additionalCommittedItems.errors.messageError message encountered while processing the additional CI.Data type: String
<String>.additionalCommittedItems.identificationAttemptsArray of objects in which each object describes an attempt made to identify this additional CI.Data type: Array of Objects 
"identificationAttempts": [
  {
    "attemptResult": "String",
    "attributes": [Array],
    "hybridEntryCiAttributes": [Array],
    "identiferName": "String",
    "searchOnTable": [Array]
  }
]
<String>.additionalCommittedItems.identificationAttempts.attemptResultOutcome 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.attributesCI 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.hybridEntryCiAttributesArray 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.identifierNameIdentifier rule used for this additional CI identification attempt.Data type: String
<String>.additionalCommittedItems.identificationAttempts.searchOnTableName of the table searched for this additional CI identification attempt.Data type: String
<String>.additionalCommittedItems.identifierEntrySysIdSys_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

Index values for CIs from the request body items array that correspond to this additional CI.Data type: Array of Numbers

"inputIndices": [
  {
    Number
  }
]
<String>.additionalCommittedItems.markersMarker values for internal use.Data type: Array 
"markers": []
<String>.additionalCommittedItems.mergedPayloadsSys\_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.operationOperation 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.warningsDescription of warnings encountered while processing this additional CI.Data type: Array of Objects 
"warnings": [
  {
    "error": "String",
    "message": "String"
  }
]
<String>.additionalCommittedItems.warnings.errorType of warning encountered while processing this additional CI.Data type: String
<String>.additionalCommittedItems.warnings.messageWarning message encountered while processing this additional CI.Data type: String
<String>.additionalCommittedRelations

Description of a dependent relationship CI that was not included in the request body relations list to insert or update.Data type: Array of Objects

"additionalCommittedRelations": [
  {
    "className": "String",
    "inputIndices": [Array],
    "markers": [Array],
    "mergedPayloadIds": [Array],
    "operation": "String"
  }
]
<String>.additionalCommittedRelations.classNameThe sys\_class\_name of this additional dependent relationship CI.Data type: String Only supported value: cmdb\_rel\_ci: The CI Relationship table.
<String>.additionalCommittedRelations.errorCountNumber of errors encountered while processing this additional dependent relationship CI.Data type: Number
<String>.additionalCommittedRelations.errorsDescription of the errors encountered while processing this additional dependent relationship CI.Data type: Array of Objects 
"errors": [
  {
    "error": "String",
    "message": "String"
  }
]
<String>.additionalCommittedRelations.errors.errorType of error encountered while processing the additional dependent relationship CI.Data type: String
<String>.additionalCommittedRelations.errors.messageError 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.markersMarker values for internal use.Data type: Array 
"markers": []
<String>.additionalCommittedRelations.mergedPayloadIdsSys\_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.operationOperation 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>.hasErrorFlag that indicates whether any item or relation has errors.Data type: Boolean
<String>.hasWarningFlag that indicates whether any item or relation has warnings.Data type: Boolean
<String>.itemsDescription of the created or updated CIs.Data type: Array of Objects 
"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.additionalRelatedItemsInformation 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 of Objects 
"additionalRelatedItems": [ 
  {
    "className": "String", 
    "inputIndices": [Array],
    "mergedPayloadIds": [Array], 
    "operation": "String",
    "sysId": "String"
  }
]
<String>.items.additionalRelatedItems.classNameClass/table name \(sys\_class\_name\) of the CI that was created or updated.Data type: String
<String>.items.additionalRelatedItems.inputIndicesIndex values for CIs from the request body items array that correspond to this related item.Data type: Array of Numbers
<String>.items.additionalRelatedItems.mergedPayloadIdsList of sys\_ids of the partial payloads that were merged into the related item.Data type: Array Table: CMDB IRE Partial Payloads \[cmdb\_ire\_partial\_payloads\]
<String>.items.additionalRelatedItems.operationType 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.sysIdSys\_id of the CI that was updated or created.Data type: String
<String>.items.classNameClass/table name \(sys\_class\_name\) of the CI that was created or updated.Data type: String
<String>.items.duplicateIndicesList of indexes of CIs that are duplicates of the current item.Data type: Array
<String>.items.errorCountNumber of errors encountered while processing the item.Data type: Number
<String>.items.errorsList of errors encountered while processing this CI.Data type: Array of Objects 
"errors": [
  {
    "error": "String",
    "message": "String"
  }
]
<String>.items.errors.errorType of error encountered while processing the CI.Data type: String
<String>.items.errors.messageError message associated with the error.Data type: String
<String>.items.identificationAttemptsList of attempts that were made to identify the CIs.Data type: Array of Objects 
"identificationAttempts": [
  { 
    "attemptResult": "String", 
    "attributes": [Array],
    "hybridEntryCiAttributes": [Array],
    "identifierName": "String",
    "searchOnTable": "String" 
  }
]
<String>.items.identificationAttempts.attemptResultResults 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.attributesList 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.hybridEntryCiAttributesList 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.identifierNameIdentifier rule used for this CI identification attempt.Data type: String
<String>.items.identificationAttempts.searchOnTableName of the table searched during the identification process.Data type: String
<String>.items.identifierEntrySysIdSys\_id for the identifier rule used to identify the CI.Data type: String Table: Identifier Entry \[cmdb\_identifier\_entry\]
<String>.items.incompleteSysIdsIf 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.infoAdditional information about the processing of the item.Data type: Array of Objects 
"info": [
  {
    "code": "String",
    "message": "String",
    "ruleSysId": "String"
  }
]
<String>.items.info.codeReclassification type that was skipped.Possible values: - SKIPPED\_CLASS\_DOWNGRADE - SKIPPED\_CLASS\_SWITCH - SKIPPED\_CLASS\_UPGRADE Data type: String
<String>.items.info.messageMessage that provides additional insights into the reason for skipping the reclassification.Data type: String
<String>.items.info.ruleSysIdSys\_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.inputIndicesIndexes 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.maskedAttributesList of attributes whose update by a non-authoritative data source was skipped as defined by the Reconciliation Rules.Data type: Array
<String>.items.operationOperation 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.partialSysIdsIf 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 describe a related CI (table lookup CI) from the request body items.lookup array.Data type: Array of Objects

"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.classNameClass/table name \(sys\_class\_name\) of the related item.Data type: String
<String>.items.relatedItems.errorsList of errors that occurred during processing of the related item.Data type: Array of Objects 
"errors": [
  {
    "error": "String",
    "message": "String"
  }
]
<String>.items.relatedItems.errors.errorType of error encountered while processing the related item.Data type: String
<String>.items.relatedItems.errors.messageError message associated with the error.Data type: String
<String>.items.relatedItems.errorCountNumber of errors detected while processing the related items.Data type: Number
<String>.items.relatedItems.incompleteSysIdsIf 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.inputIndicesIndex 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.mainIndexIndex value from the request body items array that corresponds to the CI parent of the related item. Data type: Number
<String>.items.relatedItems.inputIndices.subIndexIndex value from the request body items.lookup array that corresponds to the related item.Data type: Number
<String>.items.relatedItems.mergedPayloadIdsList of sys\_ids of the partial payloads that were merged into the CI during processing.Data type: Array
<String>.items.relatedItems.operationOperation 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.partialSysIdsIf 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.sysIdSys\_id of the related item.Data type: String
<String>.items.relatedItems.warningCountNumber of warnings encountered when processing the related items.Data type: Number
<String>.items.relatedItems.warningsDescription of warnings encountered while processing the related items.Data type: Array of Objects 
"warnings": [
  {
    "error": "String",
    "message": "String"
  }
]
<String>.items.relatedItems.warnings.errorType of warning encountered while processing the related item.Data type: String
<String>.items.relatedItems.warnings.messageMessage associated with the warning.Data type: String
<String>.items.relatedSysIdsList of the sys\_id values of the CIs used during lookup-based identification of related items.Data type: String
<String>.items.sys\_idSys\_id of the CI that was updated or created.Data type: String
<String>.relations

Description of a dependent relationship CI from the request body relations array.Data type: Array of Objects

"relations": [ 
  { 
    "className": "String",
    "errorCount": Number,
    "errors": [Array],
    "incompleteSysIds": "String",
    "inputIndices": [Array],
    "operation": "String",
    "partialSysIds": "String",
    "sysId": "String" 
  }
]
<String>.relations.classNameSys\_class\_name of this dependent relationship CI.Only supported value: cmdb\_rel\_ci: CI Relationship table. Data type: String
<String>.relations.errorCountNumber of errors encountered when processing the dependent relationship CI.Data type: Number
<String>.relations.errorsList that describes errors that were encountered while processing this dependent relationship CI.Data type: Array of Objects 
"errors": [
  {
    "error": "String",
    "message": "String"
  }
]
<String>.relations.errors.errorType of error encountered while processing the dependent relationship CI.Data type: String
<String>.relations.errors.messageError message encountered while processing this dependent relationship CI.Data type: String
<String>.relations.incompleteSysIdsIf 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.inputIndicesIndexes for the dependent relationship CI objects in the request body relations array that correspond to this dependent relationship CI.Data type: Array
<String>.relations.operationType 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.partialSysIdsIf 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.sysIdSys\_id of the dependent relationship CI.Data type: String
<String>.summaryList 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>.additionalInsertedItemCountNumber of items inserted due to processing of partial payloads.Data type: Number
<String>.summary.<class\_name>.errorCountNumber of errors encounter when processing items.Data type: Number
<String>.summary.<class\_name>.incompleteItemCountNumber of items inserted in the CMDB IRE Incomplete Payloads \[cmdb\_ire\_incomplete\_payloads\] table.Data type: Number
<String>.summary.<class\_name>.insertedItemCountNumber of items created.Data type: Number
<String>.summary.<class\_name>.partialItemCountNumber of items saved in the Partial Payload table \[cmdb\_ire\_partial\_payloads\].Data type: Number
<String>.summary.<class\_name>.skippedItemCountNumber of items that were skipped.Data type: Number
<String>.summary.<class\_name>.unchangedItemCountNumber of items that had entries but were not modified.Data type: Number
<String>.summary.<class\_name>.updatedItemCountNumber of items updated.Data type: Number
<String>.summary.<class\_name>.warningCountNumber of items that generated a warning when processed.Data type: Number

This code example shows how to obtain the payload of an ImportSet, where you can then update the payload, and then set the new payload before calling the cmdbUtil.identifyAndReconcileEnhanced() method to process the payload.

// Add this code to the onBefore transform map script
// Ability to modify the payload using get and set APIs
// Call cmdbUtil API to do Identification and Reconciliation of current row
var cmdbUtil = new CMDBTransformUtil();
cmdbUtil.setDataSource('ImportSet');
var payload = cmdbUtil.getPayload(source, map, log);
// Modify the payload here
cmdbUtil.setPayload(payload);
cmdbUtil.identifyAndReconcileEnhanced(source, map, log);
ignore = true;

if (cmdbUtil.hasError()) {
  var errorMessage = cmdbUtil.getError();
  log.error(errorMessage);
} else {
  log.info('IE Output Payload: ' + cmdbUtil.getOutputPayload());
  log.info('Imported CI: ' + cmdbUtil.getOutputRecordSysId());
}

CMDBTransformUtil - hasError()

Determines if an error occurred in the previous identifyAndReconcile() or identifyAndReconcileEnhanced() method call.

Use this method in onBefore transform map scripts.

NameTypeDescription
None  
TypeDescription
BooleanFlag that indicates whether there was an error occurred in the previously called identifyAndReconcile\(\) or identifyAndReconcileEnhanced\(\) method.Possible values: - true: An error occurred - false: No error occurred
// Add this code to the onBefore transform map script
// Call CMDB API to do Identification and Reconciliation of current row
var cmdbUtil = new CMDBTransformUtil();
cmdbUtil.setDataSource('ImportSet');
cmdbUtil.identifyAndReconcileEnhanced(source, map, log);
ignore = true;

if (cmdbUtil.hasError()) {
  var errorMessage = cmdbUtil.getError();
  log.error(errorMessage);
} else {
  log.info('IE Output Payload: ' + cmdbUtil.getOutputPayload());
  log.info('Imported CI: ' + cmdbUtil.getOutputRecordSysId());
}

Scoped equivalent

There is no scoped equivalent for this method.

CMDBTransformUtil - identifyAndReconcile(Object source, Object map, Object log)

Inserts or updates a configuration item (CI) in the Configuration Management Database (CMDB).

Use this method in onBefore transform map scripts. Using this method instead of relying on the transform to insert or update the configuration item record reduces duplicate entries in the CMDB. For additional information, see Apply CI Identification and Reconciliation to Import Sets.

To prevent the transform from adding or updating the record a second time, set ignore = true.

NameTypeDescription
sourceObjectGlobal object available in transform map scripts that holds the incoming record.
mapObjectMap object available in transform map scripts that holds the current transform map record.
logObjectLog object available in transform map scripts.
TypeDescription
void 

This code example shows how to call the identifyAndReconcile() method to process the current row of the input payload.

// Add this code to the onBefore transform map script
// Call CMDBTransformUtil API to do Identification and Reconciliation of the current row
var cmdbUtil = new CMDBTransformUtil();
cmdbUtil.identifyAndReconcile(source, map, log);
ignore = true;

CMDBTransformUtil - identifyAndReconcileEnhanced(Object source, Object map, Object log)

Inserts or updates a configuration item (CI) in the Configuration Management Database (CMDB).

In addition to providing the functionality of the CMDBTransformUtil.identifyAndReconcile() method, this method also supports:

  • Handling partial payloads
  • Handling partial commits
  • Removing duplicate items within a payload
  • Generating output summaries

For additional information on Identification and Reconciliation and more detailed explanations of the data used by this method, see Identification and Reconciliation (IRE).

NameTypeDescription
sourceObjectGlobal object available in transform map scripts that holds the incoming record.
mapObjectMap object available in transform map scripts that holds the current transform map record.
logObjectLog object available in transform map scripts.
TypeDescription
None 

This code example shows how to call the identifyAndReconcileEnhanced() method to process the passed in payload.

// Add this code to the onBefore transform map script
// Call CMDBTransformUtil API to do Identification and Reconciliation
var cmdbUtil = new CMDBTransformUtil();
cmdbUtil.identifyAndReconcileEnhanced(source, map, log);
ignore = true;

CMDBTransformUtil - logTransformStats(Object log)

Logs the number of configuration items (CI) inserted, updated, skipped, or that had errors.

Use this method in onComplete transform map scripts.

NameTypeDescription
logObjectLog object available in transform map scripts.
TypeDescription
void 
var cmdbUtil = new CMDBTransformUtil();
cmdbUtil.logTransformStats(log);

Scoped equivalent

There is no scoped equivalent for this method.

CMDBTransformUtil - setDataSource(String source)

Sets the data source to use when the identifyAndReconcile() or identifyAndReconcileEnhanced() method is called.

Use this method in onBefore transform map scripts. If this method is not called, the default value ImportSet.

NameTypeDescription
sourceStringData source for the source configuration item record.
TypeDescription
void 
// Add this code to the onBefore transform map script
// Call CMDB API to do Identification and Reconciliation of current row
var cmdbUtil = new CMDBTransformUtil();
cmdbUtil.setDataSource('ImportSet');
cmdbUtil.identifyAndReconcileEnhanced(source, map, log);
ignore = true;

if (cmdbUtil.hasError()) {
  var errorMessage = cmdbUtil.getError();
  log.error(errorMessage);
} else {
  log.info('IE Output Payload: ' + cmdbUtil.getOutputPayload());
  log.info('Imported CI: ' + cmdbUtil.getOutputRecordSysId());
}

Scoped equivalent

There is no scoped equivalent for this method.