Articles in this section

Automate error handling with custom hooks

If you're comfortable writing JavaScript, you can use hooks in a custom flow to handle specific errors automatically — without waiting for integrator.io's built-in auto-resolve behavior to apply. This article covers two techniques: ignoring a specific error automatically, and sending error data to an external listener. Hooks apply only to custom flows; they're not available for Integration app flows.

For an API-based alternative that doesn't require writing flow-level scripts, see Use the "Error automation via integrator.io APIs" template.

Automatically ignore a known, harmless error

Some destination applications don't offer a way to check whether a record already exists before you try to insert it. When that's the case, you may know from experience that a specific, recurring error is safe to ignore — for example, a duplicate-record response you don't need surfaced as a notification.

Consider a flow that syncs Shopify refunds with NetSuite. Some imported customers have a subsidiary value that shouldn't be updated, and those records consistently produce this error:

"responseData": [
  {
    "statusCode": 422,
    "errors": [
      {
        "_userId": "5d93d813fe3c7b0ef52e58e8",
        "resolved": false,
        "code": "cant_modify_sub",
        "message": "Failed to save record because You cannot change the subsidiary of this entity because one or more transactions exist for this entity.",
        "source": "netsuite",
        "exportDataURI": null,
        "traceKey": "2178928902215"
      }
    ],
    "ignored": false,
    "id": "ExampleID",
    "_json": {ExampleJSON},
    "dataURI": "ExampledataURI"
  }
]

A postSubmit hook can check for that specific error message and mark it ignored, so it doesn't generate a notification or sit in your Open errors list:

function postSubmitNSCreateCustomerError(options) {
  let responseData = processPostSubmitErrors(options, ignoreCreateCustomerErrorFn)
  return responseData
}
function ignoreCreateCustomerErrorFn(options) {
  let toReturn = {ignored: options.ignored, betterMessage: options.message}

  // Check for specific error message inside "errors"
  if (options.source === 'netsuite' &&
      options.code === 'cant_modify_sub' &&
      options.message.includes('Failed to save record because You cannot change the subsidiary of')) {
    toReturn.ignored = true
    toReturn.betterMessage = ''
  }
  return toReturn
}
function processPostSubmitErrors(postSubmitOptions, myProcessErrorFunction) {
  postSubmitOptions.responseData.forEach(function(rd, i) {
    if (rd.statusCode !== 422) return
    let processedErrors = []
    rd.errors.forEach(function(re) {
      let errsHelper = []
      let parsedMessage = re.message
      try {
        parsedMessage = JSON.parse(re.message)
      } catch (ex) {}
      // Modify the following for your needs.
      if (typeof parsedMessage === 'object') {
        if (Array.isArray(parsedMessage)) {
          errsHelper = parsedMessage
        } else if (Array.isArray(parsedMessage.errors)) {
          errsHelper = parsedMessage.errors
        } else {
          errsHelper.push({code: re.code, message: re.message})
        }
      } else {
        errsHelper.push({code: re.code, message: re.message})
      }
      errsHelper.forEach(function(e) {
        let processedErrorMessage = myProcessErrorFunction({
          code: e.code || re.code,
          message: e.message || re.message,
          source: re.source,
          ignored: re.ignored,
          preMapDataRecord: postSubmitOptions.preMapData[i]
        })
        processedErrors.push({
          code: e.code || re.code,
          message: processedErrorMessage.betterMessage || e.message || re.message,
          source: re.source,
          ignored: processedErrorMessage.ignored || re.ignored
        })
      })
    })
    rd.errors = processedErrors
    let allErrorsIgnored = true
    for (let j = 0; j < processedErrors.length; j++) {
      if (!processedErrors[j].ignored) {
        allErrorsIgnored = false
        break;
      }
    }
    if (allErrorsIgnored) {
      rd.ignored = true
      rd.errors = []
      if (!rd._json) rd._json = {}
      rd._json.ignoredErrors = processedErrors
    }
  })
  return postSubmitOptions.responseData
}

The conditional block inside ignoreCreateCustomerErrorFn is the part to adapt: match on the source, code, and message text specific to the error you want to ignore. You can test the function's output directly in the script editor before applying it to your flow.

Send error data to an external listener

If you need to pull information out of an error's retry data for further research outside integrator.io — for example, to log it in an external system or route it to a team channel — you can write a postSubmit hook that sends the payload to a listener in a real-time flow.

  1. On an import step, add a JavaScript hook.
  2. Select a script file or start a new one, and specify the entry-point function.
/*
* postSubmitFunction 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:
* 'preMapData' - an array of records representing the page of data before it was mapped.
*                A record can be an object {} or array [] depending on the data source.
* 'postMapData' - an array of records representing the page of data after it was mapped.
*                 A record can be an object {} or array [] depending on the data source.
* 'responseData' - an array of responses for the page of data that was submitted to the
*                  import application. An individual response will have the following
*                  fields:
*    'statusCode' - 200 is a success. 422 is a data error. 403 means the connection went
*                   offline.
*    'errors' - [{code: '', message: '', source: ''}]
*    'ignored' - true if the record was filtered/skipped, false otherwise.
*    'id' - the id from the import application response.
*    '_json' - the complete response data from the import application.
*    'dataURI' - if possible, a URI for the data in the import application (populated
*                only for errored records).
*    '_importId' - the _importId currently running.
*    '_connectionId' - the _connectionId currently running.
*    '_flowId' - the _flowId currently running.
*    '_integrationId' - the _integrationId currently running.
*    'settings' - all custom settings in scope for the import currently running.
*
* The function needs to return the responseData array provided by options.responseData.
* The length of the responseData array MUST remain unchanged. Elements within the
* responseData array can be modified to enhance error messages, modify the complete
* _json response data, etc.
* Throwing an exception will fail the entire page of records.
*/

import { exports } from 'integrator-api'

function postSubmit (options) {

  // Response data contains error
  if (options.responseData.statusCode != '200') {
    /* Send data to a listener */
    exports.run({_id: '••••••••••••••••', listenerData: options.responseData})
  }

  return options.responseData
}

Replace the masked _id with the ID of the listener export you want to receive the data. A typical flow for this pattern branches from the webhook listener step to both a destination that stores the error and a notification step — for example, a message to a team channel. See Send flow step error count to a Slack channel for a related pattern that builds on this same postSubmit/listener approach.

Keep in mind that the data a hook receives this way doesn't include the error ID, so you can't use it to retry or resolve the original error automatically.