Tray Platform / Logs and Troubleshooting / Error Handling

Error Handling

Introduction

Note that this guide is for the main Tray platform. If you are an Embedded customer please see the Error Handling guide for Tray Embedded edition

If any of the steps in your workflow encounter errors when communicating with third-party services (e.g. your Opsgenie API key doesn't have the correct access rights or you are trying to access a record that does not exist in Salesforce, Marketo etc.), you can choose how you would like to handle these errors.

Error handling templates

Please note that we have the following error handling templates available to help you qickly set up powerful and effective error alerts:

These both apply to the Stop workflow method of error handling.

Before using these templates you should familiarize yourself with all the points on this page.

Important notes

Identifying errors

The error handling methods explained below only concern error messages returned by third-party service APIs when operations are communicating with them. If misconfigured, some operations will fail in the Tray workflow builder before they communicate with the service.

For example, if you are using the Slack Send message operation and have changed the channel drop-down to a jsonpath but mis-form your jsonpath (e.g. by entering steps.trigger.data instead of $.steps.trigger.data) then the connector will not actually send a request to the Slack service API in order to receive a recognized error message.

To illustrate this, in the following workflow section the Set slack name in list data storage step might fail your workflow because it uses the $.steps.sheets-1.results[0][0].result[1]} jsonpath to get a name which was looked up in Google Sheets, and Sheets could return an empty result:

set-name-in-list-error-example

The problem here is that if Google Sheets returns an empty result, it is not considered an error by the Google Sheets API - it is just informing you that the result is empty (note that some services will return an error for empty results - it depends on how the service API works!).

Subsequently, when the Set slack name in list step attempts to retrieve the result you will get the following Tray system error:

"message": "Reference: $.steps.sheets-1.results[0][0].result[1] in property: 'value[]' did not resolve to any value."

Because this is not an API Error message returned by a third party, you will not be able to use the continue / manual / stop methods discussed below.

So we deal with this by setting a

We know that we needed to check for an empty array because inspection of the logs on the left shows that the result can be:

sheets-empty-array

If the result of this is true (i.e. it is not an empty array) then we can set the name in the list.

If it is false, then we take no action and just continue the loop to process the next name in the list.

For these types of errors, this is how we can set up an equivalent of the 'continue' error option as described below. For your own use case, you may wish to put extra steps in the false branch, to create an equivalent of the 'manual' option described below.

Retries

Errors are only sent to alerting workflows once all retries of a workflow have failed.

Multiple workflows can use the same Alerting Workflow but a workflow can't send its errors to more than one Alerting Workflow.

Available methods

There are 3 ways of dealing with errors:

  1. Continue - if the error is insignificant then you can continue the workflow as normal

  2. Manual - it is possible to create 'Success' and 'Error' branches coming from the connector step in question, so that you can set exactly what happens in the workflow should an error be encountered with this step. This works much the same as a boolean connector

  3. Stop workflow (default) - in this case the workflow is stopped and an error payload can be sent to an error handling workflow which you need to set up

Choosing the Error Handling method

For any connector step, you can find the Error Handling method drop-down by scrolling down to the very bottom of the operations panel:

error-handling-drop-down

The Continue workflow option

If you select the Continue option the workflow will continue on to the next step, but you will notice that the step in question has a blue alert symbol next to it:

continue-alert-symbol

Note that you should be careful about using the continue method as, if other steps are dependent on any output data from it, it could break your workflow.

The Manual option

If you choose Manual Alerting you will see a green success and red failure branch coming from your connector step. So you can then, for example, send an alerting email (this is of course a very simple example, and you could use the error branch to build a sophisticated alternative route for your workflow):

opsgenie-manual-error-workflow

The above example shows how to compile a simple email (this could also be a message to a Slack channel or any other option you might want to implement) which makes use of the error message from the output of the errored step.

Accessing error messages

Looking at the debug output of an errored step shows you what fields are available:

opsgenie-debug

Note: when referencing the error message from the step, it must be done in the format $.errors.<step-name>.message. The above example makes use of interpolated mode by inserting the error into the content of the email message with {$.errors.opsgenie-1.response.body.message}

This then picks up any API errors that might be generated and sends them in a composed email such as:

error-handling-email

The Stop Workflow (Default) option

Please note we have the following templates available which make use of this option:

Errors can be sent to another workflow and that workflow is responsible for handling the alerting. One case for this would be to use the HTTP connector to pass on any errors to your monitoring system of choice.

There are two steps to setting this up:

  1. Create an alerting workflow using the Alerting Trigger

  2. Configure your alerting workflow to receive errors

An enabled alerting workflow can be set as:

  • The alerting workflow for individual workflow(s) in the same workspace (org or personal)

  • The alerting workflow for all workflows in the organization workspace

  • The alerting workflow for all workflows in a user's personal workspace

Creating an alerting workflow

Create a new workflow and select the Alerting Trigger:

alert-trigger-icon

This is a special kind of trigger that can accept alerting payloads from other workflows.

You can use the connector snake to access the jsonpaths within the alert payload:

alert-trigger-snake-to-payload

The error information can then be gathered and sent to a destination of your choice:

  • A dedicated email address

  • A dedicated Slack channel

  • A Google Sheet or SQL database of errors

You could also set up a streaming service which could digest the alert trigger payload as a step event type

Basic alerting payloads

Enhanced alerting payload

Configuring your alerting workflow to receive errors

Note on services failing

If a third party being used in your workflow is having network issues, this can cause your whole workflow to fail.

A best practice approach to consider here is to set your service connectors to use Manual error handling so that you can take immediate appropriate action should this be the case.

At the end of your Error Handling branch you could then add a Terminate connector which uses the Fail run operation - set to the default 'Stop workflow' in order to send off to an alerting workflow, if required:

service-error-terminate-fail-run

Simple error handling setup

Here we will show you how to use a callable workflow to allow for workflow run-specific logging and error handling 

Once you have completed the above steps you will have a parent workflow that calls a callable (child) workflow that performs some data processing in parallel.

Each run of the callable workflow will have its own logging allowing for easier issue identification and resolution as well as its own error handling flow.