CMDBTransformUtil - Global

  • Release version: Yokohama
  • Updated January 30, 2025
  • 24 minutes to read

    • 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.

    CMDBTransformUtil - CMDBTransformUtil()

    Creates a CMDBTransformUtil object.

    Table 1. Parameters
    Name Type Description
    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.

    Table 2. Parameters
    Name Type Description
    None
    Table 3. Returns
    Type Description
    String Error 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.

    Table 4. Parameters
    Name Type Description
    None
    Table 5. Returns
    Type Description
    <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 Description 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.additionalRelatedItems List 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.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 List of errors encountered while processing this CI.

    Data type: Array of Objects

    "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 of Objects

    "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.

    Data type: String

    Table: Identifier Entry [cmdb_identifier_entry]
    <String>.items.info List 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.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 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.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 of Objects

    "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 Information about the processed relations.

    Data type: Array of Objects

    "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

    		 
    // 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.

    Table 6. Parameters
    Name Type Description
    None
    Table 7. Returns
    Type Description
    String Sys_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.

    Table 8. Parameters
    Name Type Description
    source Object Global object available in transform map scripts that holds the incoming record.
    map Object Map object available in transform map scripts that holds the current transform map record.
    log Object Log object available in transform map scripts.
    Table 9. Returns
    Parameter Description
    <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 of Objects

    "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 of Objects
    "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 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 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.markers Marker values for internal use.

    Data type: Array

    "markers": []
    <String>.additionalCommittedItems.mergedPayloads 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 Description of warnings encountered while processing this additional CI.

    Data type: Array of Objects

    "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 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.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 Description of the errors encountered while processing this additional dependent relationship CI.

    Data type: Array of Objects

    "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 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 Description 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.additionalRelatedItems 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 of Objects

    "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.

    Data type: Array

    Table: CMDB IRE Partial Payloads [cmdb_ire_partial_payloads]
    <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 List of errors encountered while processing this CI.

    Data type: Array of Objects

    "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 of Objects

    "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.

    Data type: String

    Table: Identifier Entry [cmdb_identifier_entry]
    <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 Additional information about the processing of the item.

    Data type: Array of Objects

    "info": [
  {
    "code": "String",
    "message": "String",
    "ruleSysId": "String"
  }
]
    <String>.items.info.code Reclassification type that was skipped.
    Possible values:
    • SKIPPED_CLASS_DOWNGRADE
    • SKIPPED_CLASS_SWITCH
    • 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 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.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 of Objects

    "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 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 Description of warnings encountered while processing the related items.

    Data type: Array of Objects

    "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 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.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 List 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.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

    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.

    Table 10. Parameters
    Name Type Description
    None
    Table 11. Returns
    Type Description
    Boolean Flag 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.

    Table 12. Parameters
    Name Type Description
    source Object Global object available in transform map scripts that holds the incoming record.
    map Object Map object available in transform map scripts that holds the current transform map record.
    log Object Log object available in transform map scripts.
    Table 13. Returns
    Type Description
    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).

    Table 14. Parameters
    Name Type Description
    source Object Global object available in transform map scripts that holds the incoming record.
    map Object Map object available in transform map scripts that holds the current transform map record.
    log Object Log object available in transform map scripts.
    Table 15. Returns
    Type Description
    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.

    Table 16. Parameters
    Name Type Description
    log Object Log object available in transform map scripts.
    Table 17. Returns
    Type Description
    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.

    Table 18. Parameters
    Name Type Description
    source String Data source for the source configuration item record.
    Table 19. Returns
    Type Description
    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.