Skip to main content

Debugging Workflows

Orkes Conductor provides a visual representation of workflows that aids in quickly troubleshooting issues. The Conductor UI allows users to inspect workflow executions, facilitating rapid identification and resolution of problems.

Searching and Viewing Workflow Executions​

All workflow executions are listed on the Executions > Workflow page. By default, users can only view executions of permitted workflows.

Workflow Executions page

The workflow execution data can be filtered by searching through workflow name, workflow ID, correlation ID, idempotency key, status, time period, and free text search. Turn on SQL format to view the workflow execution data in SQL format.

Additionally, you can view the workflow execution as code directly from the UI by clicking the arrow in the Search button and selecting Show as code.

Show as code option in Workflow Search

This would show the workflow search data in different codes. You can get the workflow search data in cURL and JavaScript formats.

Workflow search data in code

note

Partial searches using wildcards * are supported for workflow names. For example, searching for test* will display all workflows with names containing "test".

Workflow search with wildcard support

Viewing Individual Workflow Execution

Click on a specific execution to view detailed information. A sample execution looks like this:

Sample Workflow Executions page

The page consists of the following sub-tabs:

  • Diagram - Visual representation of the workflow's status; tasks are color-coded (green for successful, red for failed, orange for completed with errors).
  • Task List - Details of tasks within the workflow.
  • Timeline - Chronological timeline of task execution times, with zoom functionality for accuracy.
  • Summary - Includes key details such as workflow ID, status, version, start/end time, and duration.
  • Workflow Input/Output - Lists inputs and outputs of the workflow.
  • JSON - Complete JSON representation of the workflow.
  • Variables - Displays variables passed using the set variable task.
  • Task-to-Domain - Mapping of tasks to domains used in the workflow execution.

Each of these tabs gives the details that can help debug workflow issues.

Debugging Executions

The Diagram tab on the workflow execution page visually represents task statuses:

Different types of errors in a failed workflow

  • Green: Successful tasks
  • Red: Failed tasks
  • Orange: Tasks completed with errors
tip

A task ends up with the status “Completed with Errors” only when it is marked as optional:true in the workflow definition. The default value of this setting is false, so it needs to be explicitly set to continue the workflow even when there are errors.

Clicking on the failed task gives the failure details. The following fields are helpful in debugging:

FieldDescription
Summary > Reason for IncompletionThis field displays the reason for task incompletion. It can capture details such as exceptions thrown by the worker, task-related exceptions such as failed to invoke HTTP endpoints, etc.
Summary > WorkerThis field shows the worker instance that polled the task. It can help dig logs if not captured by the Conductor.
InputYou can verify if the task inputs were computed and provided correctly.
OutputYou can verify the task’s output details here. If the task’s output is supplied as the next task’s input, such details can be verified from here.
LogsYou can get the logs from this tab if the task supplies logs.
AttemptIf your task was retried, you can see all the attempts and corresponding details here.

Here is a screen grab of the fields referred above.

Failure reasons for the task

Recovering From Failures​

Once the issues regarding the workflow execution failure are resolved, you can retry the failed workflows. The Actions button towards the top-right corner of the execution page provides the following options:

Workflow Recovery Options

ActionDescription
TerminateTerminates the workflow and changes the workflow status to TERMINATED.
Restart with current definitionsRestart the workflow from the beginning using the same version of the workflow definition that originally ran this execution. This is useful if the workflow definition has changed and you want to retain this instance of the original version.
Restart with latest definitionsRestart this workflow from the beginning using the latest definition of the workflow. If you've made changes to the definition, you could use this option to re-run the flow with the latest version.
Retry - from failed taskRetries the workflow from the failed task.
Re-run WorkflowClicking on this takes to the Run Workflow page, where you can rerun the workflow. While running, you can change the workflow input parameters, idempotency key, correlation ID, and task to domain mapping.
tip

Check out the documentation on native retry and error handling features, which enable tasks to be automatically retried in the event of transient failures.