Workflow Error Trigger

The Workflow Error Trigger fires a workflow whenever a halting error occurs in a separate workflow execution.

Node Properties

The Workflow Error Trigger’s configuration varies slightly depending on the type of workflow in which the trigger is used. In all cases, the configuration centers around the scope under which the trigger should execute — as in, whether the trigger should execute for errors thrown by the workflow in which it is placed, or for other errors in other workflows as well.

The level of specificity also determines the order in which Workflow Error Triggers fire if there are multiple triggers across your application.

Application Workflows

In Application Workflows, the Workflow Error Trigger may fire in a number of different scopes …

• Only trigger for errors within this workflow: The Workflow Error Trigger will only execute when a halting error occurs in the same workflow in which it is placed (including any of its versions). This option is useful for recovering from specific error cases, such as workflow timeout errors.

• Trigger when a node in the following scope causes the workflow to halt…: Select this option to fire the trigger in a broader scope. This option is useful for tracking uncaught exceptions in the error tracking software of your choice. When choosing this, you must then select one of the following sub-scopes …

  • Any Application Workflow: The trigger will fire when a halting error is encountered within any of your Application Workflows or their versions, including the workflow in which the Workflow Error Trigger is placed.
  • Any Experience Workflow: The trigger will fire when a halting error is encountered within any version of any of your Experience Workflows.
  • Any Application or Experience Workflow: This option fires the trigger under both conditions described above.

Note: The Workflow Error Trigger will only fire in the default version of an Application Workflow. It will, however, execute in the default version if any version of a scoped workflow throws an error.

Experience Workflows

In Experience Workflows, the Workflow Error Trigger may fire in two different scopes …

• Only trigger for errors within this workflow: The Workflow Error Trigger will only execute when a halting error occurs in the same workflow and version in which it is placed. This is useful for recovering from an uncaught exception and continuing to deliver an expected result to an Experience Endpoint request.
• Trigger whenever any experience workflow within the same experience version throws an error: The Workflow Error Trigger can be placed in any Experience Workflow within your Experience Version, and it will fire for a halting error within any Experience Workflow within that same version. This is useful for serving a generic 500 Internal Server Error page to your end users.

Edge Workflows

The Workflow Error Trigger is only available in Gateway Edge Agent versions 1.13.0 and higher. In those agents, the trigger only fires for uncaught exceptions encountered within the same Edge Workflow.

Starting with GEA version 1.20.0, the Workflow Error Trigger can be configured to execute in one of two scopes:

• Only trigger for errors within this workflow: The Workflow Error Trigger will only execute when a halting error occurs in the same workflow in which it is placed.
• Trigger whenever any workflow on the deployed device throws an error: The Workflow Error Trigger can be placed in any Edge Workflow deployed to your Edge Compute Device and it will fire when any workflow on the device encounters an uncaught exception. This is useful for general error tracking as well as serving a 500 Internal Server Error page when utilizing the GEA’s web server.

Payload

The initial payload for a Workflow Error Trigger includes a data property with the following properties:

• erroredPayload: The full payload of the erroring workflow execution. This will almost always be an object with a shape similar to other workflow executions, unless the original workflow execution overwrote the entire payload with a string, number, or boolean value. However, in certain scenarios, the original payload may not be present.
• errorInfo: An object describing the error that caused the Workflow Error Trigger to fire. The object contains the following properties:
  • error: An error object containing two properties:
    • message: A human-readable message describing the error as a string. If the trigger fired as a result of a Throw Error Node, the user-provided error message will appear here.
    • stack: If the error was thrown by a Function Node, this property may be present. Its value is an array of strings representing a stack trace that led to the exception.
    • name: A string stating the category of the error (for example, “ValidationError” or “PayloadTooLarge”).
  • nodeId: The ID of the node that threw the error as a string.
  • nodeType: A string representing the type of node that threw the error (for example, “MqttMessageNode” or “HttpNode”).
• replyId: If the erroredPayload included a value at data.replyId — which would occur if the original workflow fired from an Endpoint Trigger, a Webhook Trigger that was expecting a reply, or an HTTP Request Trigger — that value will be moved to the same location in the Workflow Error Trigger’s original payload. This allows you to easily use an Endpoint: Reply Node, a Webhook: Reply Node, or an HTTP Response Node respectively to issue a 500 Internal Server Error reply to your end users.

In the general case, a Workflow Error Trigger payload looks like the following (with the erroredPayload reflecting an error thrown in a Function Node that executed from a Webhook Trigger):

{
  "applicationId": "555555555555eeeeeeeeeeee",
  "applicationName": "My Great Application",
  "data": {
    "errorInfo": {
      "error": {
        "message": "Cannot read properties of undefined (reading 'bar')",
        "name": "FunctionNodeTypeError"
      }
    },
    "erroredPayload": {
      "applicationId": "555555555555eeeeeeeeeeee",
      "applicationName": "My Great Application",
      "data": {
        "body": {
          "age": "42",
          "name": "Jane"
        },
        "headers": {
          "accept": "*/*",
          "content-length": "237",
          "content-type": "multipart/form-data",
          "user-agent": "curl/7.77.0",
          "x-forwarded-for": "<source IP address>",
          "x-forwarded-proto": "https",
          "x-real-ip": "<source IP address>"
        },
        "method": "post",
        "path": "/transition/up",
        "query": {
          "location": "52"
        },
        "replyId": "<ID of webhook>.<Unique request ID>"
      },
      "flowId": "333333333333cccccccccccc",
      "flowName": "My Great Workflow",
      "flowVersion": "myFlowVersion",
      "globals": {
        "aJsonGlobal": {
          "key": "value"
        },
        "aNumberGlobal": 42,
        "aStringGlobal": "My value"
      },
      "relayId": "000000000000000000000000",
      "relayType": "public",
      "time": Fri Feb 19 2016 17:26:00 GMT-0500 (EST),
      "triggerId": "<ID of webhook>",
      "triggerType": "webhook"
    },
    "replyId": "<ID of webhook>.<Unique request ID>"
  },
  "flowId": "333333333333cccccccccccc",
  "flowName": "My Great Workflow",
  "flowVersion": "myFlowVersion",
  "globals": {
    "aJsonGlobal": {
      "key": "value"
    },
    "aNumberGlobal": 42,
    "aStringGlobal": "My value"
  },
  "relayId": "<ID of erroring workflow>",
  "relayType": "flow",
  "time": Fri Feb 19 2016 17:26:00 GMT-0500 (EST),
  "triggerId": "<ID of erroring workflow>-flowError",
  "triggerType": "flowError"
}

Notes

There are a number of considerations to make when utilizing the Workflow Error Trigger …

Scope Defines Execution Order

Generally speaking, the more closely scoped a Workflow Error Trigger is to the error that caused the execution, the earlier it will run as compared to other triggers also scoped to the error.

For example, given an error thrown within an Experience Workflow, any Workflow Error Triggers would fire in the following order …

1. A trigger in the same Experience Workflow that caused the error.
2. A trigger in another Experience Workflow in the same Experience Version.
3. A trigger in an Application Workflow scoped to fire for errors in any Experience Workflow.
4. A trigger in an Application Workflow scoped to fire for errors in any Application or Experience Workflow.

Halting vs. Non-Halting Errors

Many workflow nodes are resilient to halting errors (exceptions that make the continued execution of the workflow impossible), in that they will place an error object at the node’s Result Path when an exception is encountered instead of ending the workflow execution. Non-halting errors such as these will not fire the Workflow Error Trigger; only halting errors will cause this trigger to fire.

In the case of non-halting errors, handling these exceptions is easily done through the use of a Conditional Node to check for the presence of an expected property in the successful execution case. If the property does not exist, the Conditional Node can take the other branch and handle the error down that path.

Errors Thrown from a Workflow Error Trigger

In the event that an execution that originated from a Workflow Error Trigger throws an error itself, that error will not fire another Workflow Error Trigger. This is to prevent infinite loops of workflow executions.

For this reason, it is recommended to utilize the Workflow Error Trigger for short, simple workflow executions designed to log the error and, if applicable, issue a generic reply to the HTTP request that originally caused the error.

erroredPayload Size Limit

All workflow executions, including for the Workflow Error Trigger, have a size limit of 256KB on the initial payload. Because of this, the erroredPayload value may not include the original payload – especially in the case of “PayloadTooLarge” errors.

Instead, the value at data.erroredPayload will be a string: “Payload data omitted due to size”.

triggerId Property in Edge Workflows

In Edge Workflows, if the Workflow Error Trigger is configured to execute whenever any workflow on the deployed device throws an error, the triggerId property on the initial payload will only include the ID of the workflow that threw the error if the error was thrown by the same workflow that caused the trigger to fire. If the uncaught exception occurred in a separate workflow, the value of the triggerId field will be “global-flowError”.

If you need the ID of the workflow that caused the initial error, you will likely be able to find it at the payload path of data.erroredPayload.flowId.