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

Example

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().

Example

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

Example

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

Example

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

Example

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

Example

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

Example

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

Example

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

Example

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

Example

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