Hooks are custom code that can run at different stages during the execution of a flow to modify the behavior of export and import processes. A flow in integrator.io consists of a source (export from an app, database, or file server; or a webhook listener) and a destination (import, file transfer, or lookup). In simple terms, an export retrieves the data of the source application and breaks it into smaller pages. An import processes those pages and stores the data in the destination application. You can use different types of hooks at each stage of the integration process to perform advanced functions.

The following table lists the script formats available for each hook type.

Hook availability

Hook type	JavaScript	Stack	SuiteScript 1.0	SuiteScript 2.0
preSend			x	x
preSave	x	x
postResponseMap	x	x
preMap	x	x	x
postMap	x	x	x	x
postSubmit	x	x	x	x
postAggregate	x	x

Export hooks
- Pre save hook

Export hooks

Export hooks run during the export stage of a flow. Currently integrator supports only one type of export hook: Pre save.

Hook Types:

Script: Integrator.io manages and executes your code.
Stack: Your own server or AWS lambda hosts your code.

See the following articles for specific hook implementations:

Pre save hook

You can use this hook to format, filter, and perform logic on the data coming from your export before it moves on to the rest of your data flow. Logic that applies to the data at all steps of the integration should be done at this stage of the flow.

Common use cases:

Filter out data at a line level.
Apply calculations to the data (examples: sum of lines, calculate discounts).
Complex data formatting (example: turn comma-separated text into an array).
Perform data validation.

The Pre save hook is invoked after the export of a page is complete but before the page is sent to the destination application (import or lookup) for processing. You can use this hook to add or delete records or modify the existing records present in the data.

The Pre save hook function is passed an options argument and a callback argument.

Pre save hook options argument fields

The first argument (options) has the following fields:

Field Name	Description
bearerToken	A one-time bearer token which can be used to invoke selected integrator.io API routes.
preview	A Boolean flag used to indicate that this export is being used by the integrator.io UI to get a sample of the data being exported.
data	An array of records representing one page of data. An individual record can be an object {}, or an array [] depending on the data source.
errors	An array of errors where each error has the following structure: { code: '', message: '', source: '' }
_exportId	The _exportId currently running.
_connectionId	The _connectionId currently running.
_flowId	The _flowId currently running.
_integrationId	The _integrationId currently running.
pageIndex	0 based. context is the batch export currently running. This is sent to Pre save hooks so that developers know which page is being processed.
lastExportDateTime	This variable is sent to Pre save hooks for delta flows so that developers can programmatically exclude records using these dynamic date values.
currentExportDateTime	This variable is sent to Pre save hooks for delta flows so that developers can programmatically exclude records using these dynamic date values.
settings	A container object for all the SmartConnector settings associated with the integration (applicable to SmartConnectors only).
configuration	An optional configuration object that can be set directly on the export resource (to further customize the hooks behavior).

Pre save hook callback arguments

The function can use the following callback arguments:

Argument Name	Description
err	An error object to signal a fatal exception and will stop the flow.
responseData	An object that has the following structure: { "data":[], "errors":[{ "code":"", "message":"", "source":"" }], "abort":"true\|false" }
data	Your modified data.
errors	Your modified errors.
abort	Instruct the batch export currently running to stop generating new pages of data. module.hooks.preSavePageFunction = function (options, callback) { return callback(err, responseData) } This function is invoked at the end of the data record after the transformations and the filters. It’s the last step before the export record is passed to the destination app. The functions are available in a drop-down menu at the top of your script editor.

Pre save hook examples

Example 1:

This example runs on a set of JSON data that returns the customer’s email address in an object within an array called identity-profiles that then has objects containing of a type and value property. This hook will find the object with the type of EMAIL and set the corresponding value to the main level of the object.

function preSavePageFunction (options) {
  for(var i=0; i < options.data.length; i++){
	if(!options.data[i]['identity-profiles'] || options.data[i]['identity-profiles'].length < 1){
  	break;
	}
    
	var emailFound = false;
	for(var j=0; j < options.data[i]['identity-profiles'].length; j++){
  	if(options.data[i]['identity-profiles'][j].identities){
    	for(var k=0; k < options.data[i]['identity-profiles'][j].identities.length; k++){
      	if(options.data[i]['identity-profiles'][j].identities[k].type != "EMAIL")
        	continue;
     	 
      	options.data[i].email = options.data[i]['identity-profiles'][j].identities[k].value;
      	emailFound = true;
      	break;
    	}
  	}
  	if(emailFound)
    	break;
	}
  }
  return {
	data: options.data,
	errors: options.errors
  }
}

Example 2: You are exporting records out of an API that does NOT natively support a last modified search filter, but there is a last modified or created date field in the actual records being exported.

This use case uses the following arguments:

lastExportDateTime
currentExportDateTime
abort

Using lastExportDateTime and currentExportDateTime in your Pre save hook, you can programmatically exclude export records with date fields that fall outside of a specified range. If, during an export, you determine that all subsequent records returned will fall outside of the specified range, then you can return an abort argument at any time to stop the export from returning more records.

Note: You can both abort and return records in the same response. This instructs the export to stop retrieving more pages of records, but the flow should still process the records returned in the response.

Example 3: This use case uses the following arguments:

pageIndex
abort

You are exporting records out of an API where the first page of records contains information about the full set of records, and then based on info in the first page you decide to continue with the export, or return abort right away.

Comments

5 comments

PSA Admin

October 09, 2020 10:26

Edited
Excellent article as I get into more javascript hooks. Question: in testing and using the preview functionality of the j-hook window, is there a way to preview with more than a single object in the data[] array? Even with "All" selected in the initial export flow step, I only get data[0].

Thank you!

Jim Kelleher

(As an aside, love that you use i, j, and k as iteration variables. Takes me back to my Fortran days.)
0
Courtney Jordan Experience Strategy & Design Director Community moderator

October 09, 2020 16:37
Hi PSA Admin!
Thanks so much for the great feedback! Speaking of old languages, I still try to forget my COBOL days! ;-D I'm checking into the answer on this for you and will get back to you asap.
0
Courtney Jordan Experience Strategy & Design Director Community moderator

October 09, 2020 17:04
Hi PSA Admin,

For now, you need to copy and paste or type in additional records into the data[] arg. We're looking at having the ability to preview more than one record in the export panel for next year, which will make this process easier. You letting us know about this need is helping us consider adding the ability to pull more than one record into the Advanced Field Editors (AFEs), so thank you!
0
Shane Brown

January 12, 2021 20:59
I would also like the same functionality described by PSA Admin. Whenever I need to test against more than one object I must copy it from the debugger and then paste it into the template. It would save a lot of time to have this functionality.
0
Courtney Jordan Experience Strategy & Design Director Community moderator

January 12, 2021 21:09
Hi Shane Brown,

Thanks so much for letting us know. Could you post this enhancement idea to our community in the enhancement requests area? We are working on a feature to store and view sample data throughout the flow to show how it's being impacted at each step, as a result of PSA Admin's insights in improving this experience. Would you be interested in previewing what we're designing now?

PSA Admin, we're already planning to show you what we're working on :). Thank you so much for your invaluable help!
0

Please sign in to leave a comment.