Tray Embedded / Troubleshooting / Debugging / Error Handling / Error Handling

Error Handling

Note that this page is for Tray Embedded customers. If you are not an Embedded customer please see the Error Handling guide for the main Tray Platform

Available methods

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

  1. Continue - if the expected errors are 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 (as an Embedded customer you can choose to use either use standard error alerting or 'partner' alerting - as will be explained below)

Please see our main platform documentation on error handling for guidance on how to use the 'continue', 'manual' and 'stop' methods.

Accessing $.env and $.errors data from within your workflow

When using the manual error handling method you can use the $.errors jsonpath prefix to access the details of the error.

And there is a list of $.env variables that - at any point in your workflow - can be used to access basic info about the workflow/solution environment. These are:


For example if you have a step which produces the following error output:

You could use the following:

To format a message which would produce the following:

The execution uuid

The $.env.execution_uuid variable is potentially of key importance in managing statuses and errors. It is the id which is generated every time a workflow is run. It could be linked to an external execution id (which may have been pulled in from a webhook) - both of which could be stored in Data Storage and retrieved later in the workflow or stored at account level and retrieved in any child workflows which are called.

The stop workflow option

When using the 'Stop workflow' option you have two basic methods of error handling available:

  1. Standard Alerting (as used for the main Tray platform)

Standard alerting is set up using the main platform Alert trigger and can be used workflow-by-workflow so can allow you to set up individual workflows for specific error handling.

Please see our main platform documentation on error handling for guidance on how to use the 'continue', 'manual' and 'stop' methods.

This form of alerting includes the two main requirements for handling an error:

- The error message
- The link to the error in the logs

A key point here is that the logs linked to are the logs for the End User-specific copy of the workflow which exists within their Solution Instance, so can be used to resolve causes of errors specific to that End User.

The following screenshot shows the output schema of the data that can be retrieved from the Alerting Trigger:

  1. Partner Alerting (specific to Embedded)

Here you can create a single Partner Alerting workflow which receives all error alerts across all projects and solutions.

This is useful in terms of a 'helicopter view' of the overall health of your projects - which solutions and solution instances are causing problems.

It is generally not recommended to use this in order to actually handle and resolve errors that are occurring in your workflows, as you will have to put in all sorts of branches and conditionals to check and deal with the context and cause of the errors - resulting in an extremely complex and difficult to manage workflow.

Please see the section at the end of this document on Embedded-specific Partner Alerting for instructions on using this method.

Strategic considerations

For non-trivial errors involving the key service connector steps within your workflow, you will need to decide whether to use the manual or stop workflow method.

You should also consider if you wish to set up a complete status handling system for your workflows - i.e. you are recording and monitoring processes which are in progress and successful, as well as just failed processes which have produced an error. A recommended approach to this is detailed in our section on Inserting status / error data into MySQL

Monitoring the status of processes within your workflows will involve use of Data Storage and Date and Time Helpers to store key data points and monitor time elapsed during processing.

As early as possible you should identify who will actually be receiving these errors. Should it be:

  • The End User who can look into and resolve their own issues

  • A support team who can look into and resolve issues on behalf of your End Users and organization

This decision will be based on the nature of your application and internal systems and it will affect how you design and implement your error handling workflows.

In setting up an error handling system to communicate error information to the relevant people, you should always consider how this will actually be communicated to them, once error information has been gathered. The following are options to consider:

  • An external backend system you have built yourself. This could be in the form of a searchable task status UI, which alerts End Users when errors have occurred - including key info around the attempted operation and the copy of the error message and information needed to resolve the problem

  • An interactive component in the UI of your application interface (i.e. the same application which your End Users use to launch the Config Wizard) which surfaces the error message and information needed to resolve the problem

  • At the most simple level, the gathered error information could be sent via Email, Slack etc.

The error messages themselves can be as simple as "We are currently having trouble connecting to service X, please contact support" or as detailed as "The SDR email you have entered is not in the correct format".

Please see the recommended approaches below for guidance.

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:

Note on points of failure

You should be aware that setting up error handling systems within your workflow can add more points of failure. An example of this is when somebody might change the login credentials for the MySQL database you are using to store your status messages.

1 - Capturing End User errors with the CSV Editor

Using the CSV Editor could be seen as the 'native' way of setting up a system of dealing with errors that might have been made by your End Users in terms of both:

  • Entering, administrating and retrieving data in your external systems - i.e. your CRMs and company databases
  • Entering data into the Tray Embedded Config Wizard

An approach that could be adopted here is:

  1. A workflow is triggered - e.g. by webhook data being received from a third party which is included in your End Users' integrations

  2. Run a quick validation script to make sure that certain key fields are present in the initial payload - fail and terminate the workflow if not

  3. Initiate a CSV Errors file using the CSV Editor (likely at Account level so it can be manipulated in sub-processing workflows you may wish to call)

  4. Continue with the main workflow and processing of the data generated by your integration (i.e. responding to third party webhook data etc.)

  5. In the main part of your worklow, pick up any errors due to e.g. invalid email, contact not found, missing key info etc. (to simplify your main workflow and set up a 'sub-processing' system these checks could be made in callable workflows). Some examples of how you can format error messages in a way that is actionable are given below

  6. At the end of your workflow export the CSV and send to the required destination

The following screenshot shows an Errors CSV being initialized at Account level scope:

The Call workflow step can then use $ to pass the id of the CSV to a sub-processing workflow which can then add rows of error information to the CSV if needed.

An example of a piece of sub-processing that might be carried out in the called workflow is:

Once this is sent back to the workflow which called it, the error can be added as a row to the CSV (noting that $ is used to pull the error message from the response):

The final stage involves 'exporting' the CSV so that it can be sent to the required destination - in this case AWS S3 and Amazon SQS

2 - Inserting status / error data into MySQL

This approach has the following benefits:

  • Organize errors before recording them - e.g. group errors by customer affected, or group errors by cause (missing ID, etc.)

  • Can track stats relevant to the workflow

  • A simple way of capturing status messages / error messages

  • Can be used as the foundation for an external system set up to take action based on the errors being encountered

  • Can distinguish between partial failure and those which will terminate the workflow

An example can be seen here where we attempt to feed a status message on time spent to a database.

The first Get tables MySQL query has manual error handling set up whereby this whole section is bypassed if it returns an error.

For the Status message step note the blue warning which indicates that the error handling is set to 'continue' - i.e. we expect this attempt to update the database to error sometimes and can just continue if so:

Another example shows dealing with a case where no results are found by gathering a list of IDs to be included in a database Insert Error update (with a 'continue' error message in case no IDs are found).

This finishes with a Fail Run terminate step which will fail the workflow, as described in the above Note on services failing:

The potential drawbacks to the database approach are:

  1. Handling errors in this way can mean you are adding more points of failure - e.g. if somebody in your company accidentally changes the login credentials for your database then the whole workflow will fail (typically we’d rather set up the workflow so that we have a succesful run of the workflow and not receive the messages, than fail the run because of a failed database connection)
  2. If your database schema changes, it can be tedious to update every single connector. This can be mitigated by using a callable workflow that all errors are sent to and formatted for one database connector
  3. Requires setting up / paying for a database service
  4. Isn’t well-suited to notifying an End User without some other service to manage it

3 - Using a queue service and building your own backend system

One possible way to store and communicate status and errors to your End Users is with a queue management service such as Amazon SQS.

The above example shows the final stage of a workflow which has been set up to gather status information and send messages to SQS via a callable workflow.

From here you could build your own backend service (i.e. built by yourself as there are no specific components for this) which pulls the data from SQS to store these messages and alert the End User in order that they are presented with an error message such as 'Failed to launch campaign to Facebook. Please ensure your audience size is not below 100'.

The End User can then take the necessary action to resolve.

Embedded-specific Partner Alerting

In order to be alerted about any errors that are occurring with Solution Instances / Solutions / Workflows it is possible to build an Alerting Workflow which makes use of the Partner Alert Trigger.

This is useful in terms of a 'helicopter view' of the overall health of your projects - which solutions and solution instances are causing problems.

There are two steps to setting up Error Alerting:

  1. Create the Partner Alerting Workflow (multiple alerting workflows can be created)

  2. In your Partner account, set the Partner Alerting Workflow which will be notified when there are any errors occuring within your Projects

Note in Tray it is also possible to specify the Alerting Workflow to notify for each individual workflow you create. In order to receive Alerts at Team level you should not do this. You should set it in your Partner Account, as will be illustrated below.

Create a Partner Alerting Workflow

First of all, create a new workflow and select the Partner Alert Trigger:

From the above screenshot you will see that one way of creating an alerting workflow is to parse the error output data from the trigger step into a Slack message (you could also, for example, set up an email alert to receive the information). You can manipulate and use the output data in any way you wish, using the Tray connectors and helpers you have at your disposal.

The trigger output can be picked up with the following json path structure:


Note that the above example shows how you can parse the data into a plain text 'Message' box when you enclose the json path in '{ }' curly brackets.

To see what output is available from the trigger, you can select the Partner Alert trigger and scroll to the bottom of the step details:

The following table gives a breakdown of the output data which is returned by the Partner Trigger:

solution_idThe ID of the Solution which sent the error
solution_instance_idThe ID of the Solution Instance
source_workflow_uuidThe UUID of the source workflow which sent the error
workflow_urlThe URL of the workflow which sent the error
workflow_titleThe title of the workflow which sent the error
step_nameThe name of the specific step which was the cause of the error. Note that this is not the user-configured name but the unique name given by Tray
user_idThe Partner User ID
user_external_idThe ID of the External User
step_log_urlThis URL can be used to go directly to the point in the logs at which this error occurred
connectorThe type of connector (and version) that caused the error
messageThe internal Tray-generated error message
createdA timestamp of when the error occurred

Your alerting workflow can make use of these fields to provide useful information for debugging.

Workflows with an alerting trigger behave just like any other workflow. You can build any logic you like into your workflow to handle the incoming errors.

Specify the Partner Alerting Workflow in your Partner Account

In your Partner Account you can go to profile settings to set the alerting workflow which will be handling any errors associated with your Projects, Solutions and Workflows:

Note that only Workflows with a Project Alert Trigger will appear in this list.