Tip - Understanding preMap hooks

Integrator.io
, ,
1

It may be confusing on how use a preMap script to modify the importing record, but hopefully this tip makes it simpler. The function stub provides some template code for you that operates on each importing record already, so there is no need to do any extra looping. It will be simplest to insert your code here from the stub:

function preMap (options) {
  return options.data.map((d) => {
    // insert code here
    // d represents each importing record
    d.newField = "my new field"
    return {
      data: d
    }
  })
}

Here is an example of a new field getting added. In the middle function input window, the highlighted JSON is the record that gets passed through the script.

Screenshot 2025-03-18 at 12.38.17 PM
Screenshot 2025-03-18 at 12.38.17 PM2196×1068 421 KB

Also, many people may overlook the gray comment text above the stub, but it has all the details of the preMap function and how it can be used, so be careful not to miss it!

preMapFunction stub:
The name of the function can be changed to anything you like.
The function will be passed one 'options' argument that has the following fields:
'data' - an array of records representing the page of data before it has been mapped. A record can be an object {} or array depending on the data source.
'_importId' - the _importId currently running.
'_connectionId' - the _connectionId currently running.
'_flowId' - the _flowId currently running.
'_integrationId' - the _integrationId currently running.
'_parentIntegrationId' - the parent of the _integrationId currently running.
'settings' - all custom settings in scope for the import currently running.
'sandbox' - boolean value indicating whether the script is invoked for sandbox.
'testMode' - boolean flag indicating test mode and previews.
'job' - the job currently running.
The function needs to return an array, and the length MUST match the options.data array length.
Each element in the array represents the actions that should be taken on the record at that index.
Each element in the array should have the following structure:
'data' - the modified/unmodified record that should be passed along for processing.
'errors' - used to report one or more errors for the specific record. Each error must have the following fields: {code: '', message: '', source: '' }
Returning an empty object {} for a specific record will indicate that the record should be ignored.
Returning both 'data' and 'errors' for a specific record will indicate that the record should be processed but errors should also be logged.
Throwing an exception will fail the entire page of records.

Hope this helps!
Simon

3 Likes