How to Manage Failed Workflow Runs

Workflows may fail due to configuration issues or external problems. When an event triggers a workflow, it creates a single instance called a run. The Runs page in the CRM portal serves as your troubleshooting hub for finding and managing failed workflow runs.

Now, you can get detailed error messages and tools to diagnose and resolve issues effectively. This guide explains how to access Runs in the CRM to manage failed workflow runs.

Access and Understand the Failed Runs List

To troubleshoot workflow issues, start by reviewing the list of failed runs.

  1. From the CRM portal, navigate to Admin > Runs in the main navigation menu.

  2. A list of all workflow instances that have failed will be displayed. Successful runs will not appear on this page.

The list contains several columns to help you identify each failed run:

Column

Description

Run ID

A unique identifier for the specific workflow instance.

Resource ID

The ID of the trigger event, such as order, patient, or subscription.

Workflow Name

The name of the workflow that failed.

Trigger

The event that started the workflow.

Created At

The date and time the run was created.

Resolved

The tracking status, which can be Resolved or Unresolved. You can update the status to Resolved after you have addressed the issue.

Diagnose a Failed Workflow Run

Once you have located a failed run, the next step is to identify the cause of failure.

  1. In the Actions column for the failed run you want to investigate, click Details (the eye icon).

  2. The Workflow Run Details page will open, providing all the information you need to diagnose the problem. This page is divided into the following sections:

Section

Description

Workflow Run Overview

This shows you general information about the run, such as the Run ID, the Trigger Event, its Creation date, and its status.

Error Details

This is the most important section for troubleshooting. It contains the specific error message that caused the failure and helps you identify which step in the workflow failed. For example, the error might show an email step failed because an incorrect variable like {{email}} was used instead of {{customer.email}} .

Workflow Payload

This section displays the data from the event that triggered the workflow. You can review this information to check if the initial data was correct.

Workflow Snapshot

This shows the exact configuration of the workflow at the moment it ran. You can use this to see if there was a problem with the workflow’s setup.

Resolve a Failed Workflow Run

After diagnosing the cause of a failure, you can take several actions directly from the Workflow Run Details page. The appropriate action depends on the nature of the issue.

Common Scenarios

  1. A workflow configuration issue: A step in the workflow itself is set up incorrectly.

  2. An external or data issue: The workflow blueprint is correct, but the run failed due to invalid or missing data in the payload such as a missing patient birthdate or invalid phone number.

  3. External issue: The workflow failed due to a temporary problem with an external service. For example, a third-party API timeout or server outage.

Available Actions

Use the actions below to address the issue, whether you need to fix the blueprint, apply updates, rerun the workflow, or mark it as handled.

  • Edit Workflow: Use this to go to the workflow editor and fix a problem in the main workflow blueprint (Scenario 1).

  • Update from Blueprint: After editing the blueprint, use this to apply your new changes to this specific failed run.

  • Rerun: Use this to try running the workflow again, starting from the step that failed. This is useful after you fix a configuration issue or after an external data issue has been corrected.

  • Mark as Resolved: Use this to update the run's status for your team's tracking. This shows that you have investigated and handled the failure, even if you did not need to rerun it.

Related Articles

Now that you know how to manage and resolve failed workflow runs, you can explore these related guides.