Articles in this section

Debug your scripts in integrator.io

Stephen Brandt
Updated

This article shows you how to add debug statements to your scripts, read and filter the resulting execution log, and turn on the debug level to capture the most detailed output. It also covers what to do when individual records fail during a flow run: how to isolate a bad record instead of failing the whole job, why a delta export won't automatically retry a failed record, and how to capture the endpoint's response so you can see exactly why a record failed.

Add debug statements to your scripts

To add JavaScript debugging statements to your integrator.io scripts, call a console object method, as follows:

Method Description Level
console.debug(string1, string 2, ...) Fine-grained informational events that are most useful to debug an application. Debug
console.info(string1, string 2, ...) Equivalent methods for printing informational messages to the execution log. Info
console.log(string1, string 2, ...)
console.warn(string1, string 2, ...) Output shown in potentially harmful situations. Warn
console.error(string1, string 2, ...) Log error events that might still allow the application to continue running. Error

Integration runtime debugging is available for export and import hooks as well as transformation and filter scripts. 

Each method will write to the script’s execution log as follows:

  • Debug – written only when the debug level is turned on
  • Info – always written
  • Warn – always written
  • Error – always written

For example, log a warning message when an expected field is missing from an exported record during a preSavePage hook:

function preSavePage (options) {
  options.data.forEach(d => {
    if (!d.shipmethod) {
      // Build error message and pass order by concatenating 
      // string variable in %s - string placeholder
      console.error('Missing shipping method for order#: %s', d.order)
    }
  })
  return {
    data: options.data,
    errors: options.errors,
    abort: false
  }
}

If that condition occurs while debugging is turned on, the execution log displays output similar to the following:

360086189772-debug-2.png

Important

Statements are written to the execution log up until a JavaScript error occurs — as distinct from a console.error() call. That script error appears on the flow Run dashboard, not in the execution log.

View and filter execution logs

The execution log displays historical events and debugging output for the selected script for up to 30 days or however long your data retention plan allows. You can also apply a filter (the default is Last 15 minutes) to narrow the time frame of logs shown.

You can also filter the execution logs according to flow Step (such as an export or a lookup), Function type, and Log level.

Turn on the debug level

A debug statement, printed by console.debug(), is the highest logging level and typically produces the most verbose output. The debug level remains off until you enable the script debugger for a specific time frame.

You can start debugging in either of two places in integrator.io, depending on your requirements:

  • In Flow Builder – If your flow contains a hook and starts on a schedule or with an export or download (not a real-time flow triggered by a webhook), the flow builder shows a Scripts tab.
  • On the Scripts page – A script is a shared resource that can be used across multiple flow steps, flows, or integrations, so you can access any script from Resources → Scripts.

In the Scripts tab or page, click the Actions overflow (...) menu, and select View execution log.

To turn on the debugger, click Start debug, choose how long you want it to run, and then select Apply.

360086272591-debug-3.png

When you’re ready to debug the script, click Run now if you’re already working in Flow Builder. Of course, if your script is invoked within a flow, that flow should run jobs within the debugging time frame, whether as a result of a scheduled start or a webhook caller sending a request.

Continuing with the example above, let’s add a debug statement that returns the entire exported data object only when the debug level is set:

function preSavePage (options) {
  console.debug('Data before preSavePage hook', JSON.stringify(options.data))
  options.data.forEach(d => {
    if (!d.shipmethod) {
      console.error('Missing shipping method for order#: %s', d.order)
    }
  })
  return {
    data: options.data,
    errors: options.errors,
    abort: false
  }
}

Then, after applying the debug log level, the data object is displayed in the execution log:

360086326592-debug-4.png