The RTETransformer API provides a method to transform and store an array of messages into a record in the associated ServiceNow instance based on a provided extract, transform, and load (ETL) definition.

For example, use this API when you have JSON payload(s) that contain user information and you want to transform that information into the sys_user table using the Robust Transform Engine (RTE).

Use the sn_impex namespace when accessing this API.

For additional information, see Define Robust Transform Engine operations.

RTETransformer - RTETransformer(String transformDefinitionId, Boolean verboseLogging, String source, Number batchSize)

Instantiates an RTETransformer object.

Table 1. Parameters
NameTypeDescription
transformDefinitionId String Sys_id of the extract, transform, and load (ETL) definition to use for the transform. Located in the ETL Definitions [sys_rte_eb_etl_definition] table.

For information on creating an ETL, see Create Extract Transform Load (ETL) definitions.
verboseLogging Boolean

Flag that indicates whether to enable verbose logging and the creation of import set rows for debugging.

Valid values:
  • true: Enable logging and import set row creation.
  • false: Do not enable logging and import set row creation.
source String Name field of the import set record.
batchSize Number Number of messages to process at one time (batch). For example, if there are 10 messages in a payload, and this value is set to 2, the method runs five separate batch jobs to process all messages in the payload.

Example

The following code example shows how to instantiate an RTETransformer object for the source testSourceRecord that has a batch size of 10.

(function(/*CTIOperationRequest*/ request, /*CTIOperationResponse*/ response, /*Context*/ ctx) {    
  // Uses an ETL definition with a target table of incident, and mappings for the number and short description field
  var transformer = new sn_impex.RTETransformer("c58f1c6377110110f5455d14cd5a998b", true, "testSourceRecord", 10);
  var messages = ["{\"number\":\"testnumber\",\"short_description\":\"testdesc\"}"];
  var results = transformer.transform(messages);

  for (var i = 0; i < results.length; i++) {
    var dataList = results[i].data.incident;
    gs.log("source record id: " + results[i].sourceRecordSysId);
    gs.log("status: " + results[i].status);
    for (var j = 0; j < dataList.length; j++) {
      gs.log("number:" + dataList[j].number);
      gs.log("short desc:" + dataList[j].short_description);
    }
  }
})(request, response, ctx);

RTETransformer - transform(Array message)

Transforms and stores an array of messages into a record in the associated ServiceNow instance based on a provided extract, transform, and load (ETL) definition.

For example, if you want to transform user information into a sys_user record, you can create a message array with a single message and pass it into this transform method.

Table 2. Parameters
Name Type Description
message Array of Objects Stringified JSON objects representing the records to transform based on the ETL definition.
For example, if you want to transform a single user with the data active, email, first name, and last name to the sys_user table, the message would look similar to this: 
[
  {  
    "active":"true",
    "email":"example@servicenow.com",
    "first_name":"Jane",
    "last_name":"Doe" 
  }
]
Note: The field names must match the field/path of the source entity fields.
Table 3. Returns
NameDescription
data Data for the transformed records, organized by table name. The returned record data matches the mapped fields specified in the ETL definition.

Data type: Object

"data": {
  "tableName": []
}
data.tableName Details of the table containing the records.

Data type: Array of Objects

"tableName": [{
  "sys_id": String,
   // Other data for a single transformed record
  }]
}
For example:
"sys_user": [{ 
  "sys_id":"b29e629877130110f5455d14cd5a99ad",
  "active": "true",
  "email": "example@servicenow.com",
  "first_name": "Jane",
  "last_name": "Doe"
}]
data.tableName.sys_id Sys_id of the record within the table.

Data type: String
data.tableName.<other_ETL_info> Additional fields that were specified in the passed ETL.

Data type: Any
message If an error occurs while transforming the specified record, a message that describes the error. Null if the transform is successful.

Data type: String
sourceRecordSysId Sys_id of the import set table record. The import set table name is JSON Event Sink [imp_json_event_sink].

Data type: String
status Status of the transform, such as processed or error.

Data type: String

Example

The following code example shows how to transform and store a record in the User [sys_user] table.

(function(/*CTIOperationRequest*/ request, /*CTIOperationResponse*/ response, /*Context*/ ctx) { 
  // Uses an ETL definition with a target table of sys_user, and mappings for the active, 
  //email, first name, and last name fields
  var transformer = new sn_impex.RTETransformer("c58f1c6377110110f5455d14cd5a998b", true, "testSourceRecord", 10);
  var messages = [JSON.stringify({
    "active":"true",
    "email":"example@servicenow.com",
    "first_name":"Jane",
    "last_name":"Doe"
  }), 
  JSON.stringify({
    "active":"true",
    "email":"example2@servicenow.com",
    "first_name":"John",
    "last_name":"Deer"
  })];
  var results = transformer.transform(messages);

  for (var i = 0; i < results.length; i++) { 
    var dataList = results[i].data.sys_user;
    gs.log("source record id: " + results[i].sourceRecordSysId); gs.log("status: " + results[i].status);
    for (var j = 0; j < dataList.length; j++) { 
      gs.log("First Name: " + dataList[j].first_name);
      gs.log("Last Name: " + dataList[j].last_name);
      gs.log("Email: " + dataList[j].email;
      gs.log("Active: " + dataList[j].active;
    }
  }
}

Results:

source record id: b29e629877130110f5455d14cd5a99ad
status: PROCESSED
First Name: Jane
Last Name: Doe
Email: example@servicenow.com
Active: true
First Name: John
Last Name: Deer
Email: example2@servicenow.com
Active: true