Skip to Content

Action error handling in Jitterbit App Builder

Error handling

Most action types terminate immediately in response to an unhandled exception. The exception is logged to the event history. It is the developer's responsibility to validate the data prior to performing the action.

Business CRUD actions perform cross-platform operations. In some cases, the operation includes one or more API requests to third-party services such as REST endpoints. It is often difficult to validate the data prior to performing the action. Instead, developers need to trap and handle the exception.

To this end, business CRUD actions support the following features:

Continue on error

A business CRUD action retrieves the rule's source rows in batches and execute the event (Insert, Update or Delete) for each row in the batch. By default, an unhandled exception terminates the operation: no additional rows are processed.

When the Continue On Error option is enabled, however, the exception is caught. The action continues processing the remaining rows, and the event completes successfully. It becomes the developer's responsibility to handle any failures using an action handler.

Action handlers

An action handler is fundamentally an action. However, action handlers differ from actions in the following ways:

  • Whereas actions are registered to run before or after an event, action handlers run after an action succeeds or fails.

  • Whereas actions are bound to the data object row, action handlers are bound to the action source.

Action handlers can be used for the following purposes:

  • Recording the status of individual rows.

  • Tracking the progress of a long running business CRUD operation.

  • Correlating row failures with entries in the [EventHistory(/app-builder/documentation/public-data-objects/eventhistory/) public data object.

  • Reversing the effect of failed actions that can't be rolled-back by database [transactions(/app-builder/documentation/transactions/).

Developers can use the [event()(/app-builder/documentation/sql/functions/runtime/event) mvSQL runtime function from within action handlers to access event and row-level information, including the following:

  • contextid: A unique identifier that can be used to correlate events that occur within a single operation, e.g. the events executed by a business CRUD action.

  • rowid: A unique identifier for the row on which the event was invoked. In the case of an business CRUD rule, this refers to the target row. In the case of an action handler, this refers to the action source row.

  • source.rowid: A unique identifier for the business CRUD rule's source row. This applies to insert and update rules.

  • exception: An exception message. This value is accessible to action failure handlers if the event failed as a result of an exception.

The rowid and source.rowid properties allow developers to correlate a row-level failure with an entry in the EventHistory public data object. A typical setup might include:

  • Action: A business CRUD insert rule which targets a REST endpoint. The Continue On Error option is enabled.

  • Success Handler: A database CRUD rule which updates the action source row to indicate that the row has been processed. This can be used to report the status of an ongoing operation or to exclude the row from future runs.

  • Failure Handler: A database CRUD rule which updates the action source row to indicate that the row has failed. The database CRUD rule would use the event('rowid') function to record the row identifier.

  • Rollback Handler: Actions that reverse the effect of all successful actions occurring before a failed action. The failed action itself is not handled by this handler.

Developers should expose the failures in the user interface. For example, the developer could build a page with two panels. The first panel enumerates the failed rows. The second panel is bound to the EventHistory public data object. The latter panel is bound to the former, matching RowId to SourceRowId.