Skip to main content

Manage errors during activities

As a low code platform, Grexx Platform includes functionality to handle common errors in activities as standard. This includes displaying helpful error messages if a user attempts to submit a form without completing mandatory fields or enters the wrong kind of data, and verifying that the user has permission to perform the activity. This type of error handling helps to ensure activities are executed as designed. If you are using a system service (for example, to generate PDFs or transform data) some additional error handling may also be built in.

Nevertheless, errors may still occur during the performance of activities. This may arise when passing data between different casetypes (particularly if the data type changes) or when requesting data from an external source. You can specify what should happen if an error occurs during the performance of an activity by adding a Try catch block.

Equally, you may want to instruct Grexx Platform to return an error if particular conditions are met during the performance of an activity. You can use a Throw block to identify the conditions that constitute an error and specify the error message.

Activity behavior on error​

When an activity fails to complete successfully and returns an error, Grexx Platform will attempt to roll back (i.e. undo) all previous steps in the activity as far as possible.

For example, if an activity fails after mappings have been applied to populate fields on a form, Grexx Platform will clear those fields and revert the activity to an unsubmitted state. If the activity is a mandatory task, this means the activity becomes available to be performed again.

However, Grexx Platform cannot roll back any steps that involve interaction with an external resource, such as sending an email or making a request to an external web service. If an activity fails after steps that involve external resources have been executed, Grexx Platform will revert the activity up to the point immediately after the relevant trigger. As the activity cannot be rolled back in full, the activity remains in a submitted state.

Tip:

Where possible, we recommend using conditional logic to provide one or more alternative "happy paths" and try to avoid raising errors. This is because it is not always possible to roll back an activity in full, which can result in unexpected behavior.

Try and catch​

You can use a Try catch block to specify an alternative set of steps to perform if an error occurs during the performance of an activity.

To configure this, use the activity designer to add a Try block to the relevant stage of the activity lifecycle:

  • Add the primary steps (triggers and mappings) that you want Grexx Platform to attempt by default to the Try block.
  • Use the Catch block to specify the alternative steps that you want Grexx Platform to execute if any one of the primary steps fails.

For example, you might use a Try catch block when the primary steps involve calls to an external service which may sometimes be unavailable. By specifying an alternative set of steps that does not rely on the external service, you can ensure the activity can be performed even if the service becomes unavailable. Alternatively, you might add a Throw to the Catch in order to display a specific error message to the user (and log the error so you can view it from Developer Tools).

When an error occurs while performing a step in the Try, Grexx Platform will attempt to roll back all the steps from the Try before continuing with the steps in the Catch. As explained above, Grexx Platform will not roll back steps that involve an external resource, such as a call to a web service or sending an email. In this situation, the activity is rolled back up to the point immediately after the trigger that involves the external resource.

Catch specific errors​

By default, the steps in the Catch are performed if any error occurs. You can also use a Catch to specify steps to perform if a supported specific error occurs, such as Error while sending email.

To catch a specific error, add a Catch and select the relevant error from the Pattern picklist. Use this option with caution; specific errors may be deprecated in future. In this situation, the steps in the Catch are only performed if the specified error occurs.

You can add multiple Catch statements to a Try. This allows you to specify one set of steps if a specific error arises, and another set of steps for all other failures.

Throw error​

To instruct Grexx Platform to raise an error and roll back an activity as far as possible, use a Throw block.

  • You can use If then else rules to define conditions that should be treated as an error. For example, you might want to raise an error if a user enters a particular value into a form field.
  • You can add a Throw to a Catch to record a custom error message when an error occurs while performing the steps in the Try.

When you add a Throw block, you must specify a public error message. The message can consist of static text and/or an inline template. When the error is thrown, the public message is displayed to the user in the toast notification.

You can specify a debug error message to record in the log (available from Developer Tools). This allows you to record additional information about the error. If you do not specify a debug message, the public error message is recorded in the log instead.

Tip:

If you simply want to change the message displayed to the user when they submit the activity form, add a Context block to the Then or Else as appropriate and select Request context > Body submit message. For more information, see Apply conditional logic to activities.

Display error messages​

To display details of an error in a message to the user or include it in an email, add the error.error to text template function to the relevant template. You can also configure this function to specify the text to display if no error occurs. For more information about using templates, see Templates.

View errors​

You can view any errors that have occurred, including activities that have failed to complete and have been fully or partly rolled back, by opening Developer Tools in the relevant DTAP environment:

  • Select Platform > Task history to view details of each activity that has been generated, including if and when it was submitted.
  • Select Platform > Errors to view a list of all errors that have occurred (other than system tasks).
  • Select Platform > Messages to view any errors raised by systems tasks, such as timed events, deadline events, or task queues.
Tip:

If an error occurs during a system task, an email notification is also sent to the Platform message email specified in your My Grexx settings for the relevant DTAP environment.