Transformation events occur during the process of transforming an import set table onto a table.

These events modify the transformation behavior from any type of mapping specification. Transformation Event scripts modify the processing of the events at various stages of the transformation.

For example, the processing of a mapping operation defined using the Mapping Assist Utility can be manipulated using the event scripts. There are a number of import set JavaScript objects that are accessible during these events. These objects represent tables or portions of tables. It is important to note that what these objects refer to varies depending on the context of the event in which they are referenced.

The following is a table of all of the transform events and their contextual variables.
Note: To view the import logs, set the glide.importlog.log_to_table property to true. For more information, see Import sets properties.
Table 1. transform events and their contextual variables
Event nameEvent Parameters
onStart

When: The onStart event script is processed at the start of an import run, before any data rows are read.

Table 2. Import Set JS objects available to be referenced and their context in the onStart event
Import Set JS objectTypeContext in the onStart import set event
source GlideRecord The first row of the source table, there is no data yet since the row has not been read.
import_set GlideRecord The import set that is currently being transformed.
map GlideTransformMap Read-only information about the current transform map record.
log Function The log object for the current import run. For example, log.info(...), log.warn(...), log.error(...).
ignore Boolean When set to true, the entire transformation will be stopped and no further processing will occur.
error Boolean When set to true, has the same effect as the ignore flag of stopping the entire transformation, with an error message.

Example:

var info = "Starting Import Set Transformation Mapping operation using Data source, " 
+ map.table_source + " and Transform Map " + map.name + " on import set " + import_set.number;
log.info( info );
onComplete

When: The onComplete event script is processed at the end of an import run, after all data rows are read and transformed.

Table 3. Import Set JS objects available to be referenced and their context in the onComplete event
Import Set JS objectTypeContext in the onComplete import set event
source GlideRecord The last row of the source import set table.
target GlideRecord The last row of target table.
import_set GlideRecord The import set that is currently being transformed.
map GlideTransformMap Read-only information about the current transform map record.
log Function The log object for the current import run. For example, log.info(...), log.warn(...), log.error(...).
error Boolean When set to true, will mark the current import set status to error after it completes.

Example:

// Create a myimport_completed event that can be reacted by an email notification or script action
// (there is already an import.finished event that the system will create at the end of an import)
var e = new GlideEvent("myimport_completed", import_set.sys_id, map.sys_id, "");
e.insert();
onBefore

When: The onBefore event script is processed at the start of a row transformation, before the source row is transformed into the target row.

Table 4. Import Set JS objects available to be referenced and their context in the onBefore event
Import Set JS objectTypeContext in the onBefore import set event
source GlideRecord The row of the source table that is currently being processed.
target GlideRecord The row of the target table that is currently being processed.
import_set GlideRecord The import set that is currently being transformed.
map GlideTransformMap Read-only information about the current transform map record.
log Function The log object for the current import run. For example, log.info(...), log.warn(...), log.error(...).
action String Action returns a value of either "insert" or "update" indicating whether the current target row is about to be created or updated.
ignore Boolean When set to true, the current row transformation will be skipped and the remaining rows will be processed.

If you have defined an onAfter script, the onAfter script runs for the current row even if the ignore flag is set to true.
status_message String Defines a custom message to be sent in the <status_message> XML response.
error Boolean When set to true, will halt the entire transformation for the current import set, with an error message.
error_message String Defines a custom message to be sent in the <error_message> XML response.

Example:

var name = source.u_name.toString();
var info = "Before the row is transformed, " + name;
log.info( info ); 
 
// Make sure a company name has been provided
var company = source.u_company.toString();
if(company.length == 0 ){
	ignore = true;
	info ="No company name, row ignored! " + name;
	log.info( info );
}
onAfter

When: The onAfter event script is processed at the end of a row transformation, after the source row has been transformed into the target row and saved.

Table 5. Import Set JS objects available to be referenced and their context in the onAfter event
Import Set JS objectTypeContext in the onAfter import set event
source GlideRecord The row of the source table that is currently being processed.
target GlideRecord The row of the target table that is currently being processed.
import_set GlideRecord The import set that is currently being transformed.
map GlideTransformMap Read-only information about the current transform map record.
log Function The log object for the current import run. For example, log.info(...), log.warn(...), log.error(...).
action String Action returns a value of either "insert" or "update" indicating whether the current target row was created or updated.
status_message String Defines a custom message to be sent in the <status_message> XML response.
error Boolean When set to true, will halt the entire transformation for the current import set, with an error message.
error_message String Defines a custom message to be sent in the <error_message> XML response.

Example:

if(source.new=="true"){
  gs.include('Cart');var bundle =new GlideRecord('sc_cat_item');
  bundle.addQuery('name','CONTAINS','comp');
  bundle.query();
  if(bundle.next()){
     var new_comp_cart = new Cart();
     var cart = new Cart();
     var item = cart.addItem(bundle);
     var rc = cart.placeOrder();
     log.info(rc.number);}}
onForeignInsert

When: The onForeignInsert event script is processed at the start of the creation of a related, referenced record, before the record is created.

Table 6. Import Set JS objects available to be referenced and their context in the onForeignInsert event
Import Set JS objectTypeContext in the onForeignInsert import set event
source GlideRecord The row of the source table that is currently being processed.
target GlideRecord The row of the target table that is currently being processed.
map GlideTransformMap Read-only information about the current transform map record.
log Function The log object for the current import run. For example, log.info(...), log.warn(...), log.error(...).
action String Action returns a value of either "insert" or "update" indicating whether the current target row is about to be created or updated.
name String Evaluates to the field name of the target record for which a foreign record that is about to be created.
value String Evaluates to the display value from the source record for which a foreign record is about to be created.
ignore Boolean When set to true, ignores the creation of a new foreign or related record.
error Boolean When set to true, rejects the entire transformation row, no data is saved for this row.

Example:

//Create an event.
var e = new GlideEvent("myimport_ForeignInsert", action, name, "");
e.insert();
onChoiceCreate

When: The onChoiceCreate event script is processed at the start of a choice value creation, before the new choice value is created.

Table 7. Import Set JS objects available to be referenced and their context in the onChoiceCreate event
Import Set JS objectTypeContext in the onChoiceCreate import set event
source GlideRecord The row of the source table that is currently being processed.
target GlideRecord The row of the target table that is currently being processed.
map GlideTransformMap Read-only information about the current transform map record.
log Function The log object for the current import run. For example, log.info(...), log.warn(...), log.error(...).
action String Action returns a value of either "insert" or "update" indicating whether the current target row is about to be created or updated.
name String Evaluates to the field name of the target record for which a choice value is about to be created.
value String Evaluates to the display value from the source record for which a choice is about to be created.
ignore Boolean When set to true, ignores the creation of a choice value.
error Boolean When set to true, rejects the entire transformation row, no data is saved for this row.

Example:

//Create an event
var e = new GlideEvent("myimport_ChoiceCreate", action, value, "");
e.insert();
onReject

When: The onReject event script is processed during the occurrence of a foreign record or choice creation, and the foreign record or choice is rejected ,the entire transformation row is not saved.

Table 8. Import Set JS objects available to be referenced and their context in the onError event
Import Set JS objectTypeContext in the onError import set event
source GlideRecord The row of the source table that is currently being processed.
target GlideRecord The row of the target table that is currently being processed.
map GlideTransformMap Read-only information about the current transform map record.
action String Action returns a value of either "insert" or "update" indicating whether the current target row is about to be created or updated.
log Function The log object for the current import run. For example, log.info(...), log.warn(...), log.error(...).
Example:
//Create an event
var e = new GlideEvent("myimport_onReject", action, "", "");
e.insert();