When a failing submission has exhausted all of its flow blocks’ retry attempts, it will have a Halted status and a Failed flow run. To alert members of your organization of the Failed flow run, you can choose an on-error flow for each of your flows.
The default on-error flow will send a notification that contains information about the failed flow run via an HTTP Output or Message Queue Notifier connection. If the flow run was processing a submission, the notification will also include a submission object with information about the submission being processed:
```
{
"flow_run": {...}, // https://docs.hyperscience.com/#flow-run-object
"submission": {...} // https://docs.hyperscience.com/#submission-objects
}
```In the screenshot below, the submission object in the flow’s output is shown on the Flow Run page. To learn more about the options available on this page, see Testing and Debugging Flows.
The recipients of the notification can use the data provided to troubleshoot the error. If additional information is required, they can use the submission id in the notification to find the submission’s details page in the application (<application_url>/submissions/<submission_id>). If needed, they can then take action to process the flow’s submission using some other method. In this way, on-error flows can help your organization meet SLAs for time-sensitive submissions.
If the default on-error flow does not meet the needs of your organization, you can create a custom on-error flow with the Flows SDK. For more details, see Creating an on-error flow.
As a best practice, we recommend selecting an on-error flow for each of your top-level flows. You can select an on-error for flow for any flow in v39, regardless of whether that flow was created in previous versions or whether it processes submissions or Unstructured documents.
Note that on-error flows are not meant to replace an observability stack; they are designed to complement existing monitoring tools by proactively notifying your organizations of failed flow runs.
Example: If submissions are failing due to critical infrastructure issues, such as a database malfunction, the on-error flow will also not run. The issue preventing the on-error flow from running—and causing submissions to fail—cannot be detected without other system-monitoring tools in place.
Creating an on-error flow
V39 includes one out-of-the-box on-error flow ("On-Error with included Submission data V39"), but you can create additional on-error flows by:
duplicating "On-Error with included Submission data V39" (to learn how, see Managing Flows), or
creating one from scratch with the Flows SDK.
Flow developers can designate a flow as an on-error flow by setting its roles value to on_error. For more information, see the Flows SDK documentation.
Configuring the output connection for an on-error flow
Before you use an on-error flow, you need to set up the output connection that it should use to send notifications.
The instructions below apply to the on-error flow included in v39. If you're setting up an on-error flow that your organization's developers created, the block names and available connection options may differ.
To set up the output connection:
Go to the All Flows page (Flows > All Flows), find the on-error flow that you would like to configure, and click on its name.
Click on the JSON Outputs block, and click Add in the block settings.
Select either HTTP Notifier or Message Queue Notifier, and follow the instructions in either HTTP Notifier or Message Queue Notifier to finish configuring the connection.
Assigning an on-error flow
In order for an on-error flow to run after another flow fails, you need to select the on-error flow in the If Flow Fails section in that flow's settings.
You can assign on-error flows to both top-level flows and subflows. If a subflow and a top-level flow in a flow group have on-error flows assigned to them, and the subflow exhausts its retry attempts, the on-error flows for both the subflow and the top-level flow will run.
Assign an on-error flow to a top-level flow
On the Top-level Flows page (Flows > Top-level Flows), find the top-level flow you want to assign an on-error flow to, and click on its Open → link.
In the table on the flow details page, click on the name of the top-level flow.
In Flow Studio, scroll down the left-hand sidebar to find the If Flow Fails section. In the Flow to Run drop-down list, click the name of the on-error flow that you want to run when the flow you're currently viewing fails.
If you would like more information about the flow you have chosen, click the View Flow link under the drop-down list to see the flow in Flow Studio.
Click Save in the upper-right corner of the page.
Assigning an on-error flow to a subflow
In the application, you can assign on-error flows only to subflows that are not read-only. A read-only flow is a flow that has read_only in its roles property. You can assign on-error flows to these flows through the Flows SDK.
To assign an on-error flow to a subflow that is not read-only:
Go to the All Flows page (Flows > All Flows), find the flow you want to assign an on-error flow to, and click on its name.
In Flow Studio, scroll down the left-hand sidebar to find the If Flow Fails section. In the Flow to Run drop-down list, click the name of the on-error flow that you want to run when the flow you're currently viewing fails.
If you would like more information about the flow you have chosen, click the View Flow link under the drop-down list to see the flow in Flow Studio.
Click Save in the upper-right corner of the page.