Operate Workflows
The Workflows page in the Catalyst console gives platform engineers and business operators a live view of workflows across a projects.
Next sections will show the Catalyst Console features that will help in different scenarios:
- Incident response: A downstream service is failing. Find and a pause affected instances stuck retrying on the service, fix or scale the downstream system, then resume.
- Forensics on a failed instance. A workflow failed. Pull its history to see the exact activity that failed, the input it was called with, and the recorded exception.
- Verifying integrity. A workflow runs a regulated process. Confirm its recorded history has not been altered, and identify any instance whose signed history has been tampered with.
For managing workflows using the cli, see diagrid workflow subcommand reference
Workflows list
The Workflows view shows a summary of the executions per workflow, including number of executions and an execution status breakdown. Expanding a workflow entry in the list shows the detailed execution statistics by status.
Workflow details
Selecting a workflow from the workflows view displays details of the most recent executions, with a breakdown by the execution statuses and a graph of the execution history.
Selecting an execution from the list shows the execution details view.
Selecting a node from the graph filters executions that executed this particular event. This is useful to quickly search for workflows that executed a conditional activity such requesting approval or fraud analysis.
The filter dialog allows further filtering by the status of the selected node and the status of the execution. This allow, for example, filtering all running executions that failed in the "notify" activity.
For each execution listed in the view is possible to execute actions. See Workflow execution actions for details of available actions.
All Workflow Executions view
The All workflow executions view shows a list of executions of workflows across all apps, with their execution status, creation time and execution time.
Filtering workflow executions
The workflow executions list can be filtered by multiple criteria such as execution status, name, app, execution time, and others.
Executing actions
For each execution listed in the view is possible to execute actions. See Workflow execution actions for details of available actions.
Workflow execution details
Selecting a workflow execution displays the details of the execution: input, output and the history graph.
Graph node details
Selecting any node in the graph opens a details dialog. For example, selecting a failed activity the inputs, outputs and the error message, if any. In this example, we can see the stack trace.
Event history
The history shows a step-by-step trace of the execution. This is useful for debugging workflow executions.
Verify execution history
On a project created with workflow verification enabled, Catalyst signs each workflow's history in blocks and re-verifies it whenever an instance is read. Signed projects are marked with a History signing enabled chip on the Workflows page. See Tamper-evident attestation for what each status means.
Execution verdict and signature details
Opening an execution shows its verdict as a badge next to the workflow name: History verified, History tampered, or Not verified.
The Verification details panel breaks the verdict down — how many events are covered by valid signatures, each signature block, and for each block the Signing identity: the SPIFFE identity of the workload that produced it, with its full certificate chain available under View certificates.
Per-step verification
The History tab annotates every step with its own verification status, and the execution graph marks verified steps with a verification seal. Selecting a node shows whether the signed records of its scheduling and completion verified.
Spotting tampered executions
In the All workflow executions view, a tampered instance is flagged with a red marker next to its workflow name and is shown as FAILED:
Opening it shows the full verdict: a History tampered badge, a banner explaining that its persisted history no longer matches its signatures — with a link to review the affected steps in the History tab — and the Verification details summary of how many events are signed.
The History tab marks exactly which events failed verification, so you can see what the tampering touched. Use the Show unverified/tampered only filter in the toolbar to jump straight to the affected steps:
To verify from the CLI or produce portable proof an auditor can check offline, see Verify workflow execution history.
Workflow execution actions
The action menu on each execution — in the workflow details view and in the all workflow executions view — offers Run new from, Suspend, Resume, Raise event and Terminate.
Which of them you can use depends on the execution's lifecycle state. An action that does not apply to the current state stays in the menu but is disabled, with a tooltip explaining which states it accepts:
| Action | What it does | Available when the execution is |
|---|---|---|
| Run new from | Starts a new execution from a chosen event in this one's history | Completed, Failed or Terminated |
| Suspend | Stops the runtime dispatching new work for the execution | Running |
| Resume | Restarts dispatch for a suspended execution | Suspended |
| Raise event | Delivers an external event the execution is waiting on | Running, Pending or Suspended |
| Terminate | Ends the execution before it completes | Running, Pending or Suspended |
Two exceptions apply to every action in the table:
- A stalled execution offers no actions at all.
- A durable agent workflow does not support the workflow management APIs, so its actions are always disabled.
The same operations are available from the CLI as diagrid workflow rerun, pause, resume, raise-event and terminate. The CLI also has diagrid workflow purge, which has no console equivalent yet, and which accepts --bulk to purge every execution matching a set of filters.
The workflow worker application must be running for these actions to take effect. Requesting any of them while the worker application is not running returns an API error.
History archival
Workflow execution history can be archived to cheaper, long-term storage. This keeps an audit of workflow executions for compliance and traceability over years, without paying to hold every execution in the more expensive database.
Archival writes through a Dapr output binding, so you can use any supported output binding as the archive destination. Configure it per app, naming both the destination binding and at least one terminal state to archive:
diagrid app create <my-app> --archive-binding-name <my-binding> --archive-binding-type <my-archive-binding-type> --archive-completed
The three state flags — --archive-completed, --archive-failed and --archive-terminated — are each off by default, so a destination configured without any of them archives nothing. Combine them to cover more than one terminal state.
To add or change archiving on an app that already exists, pass the same flags to diagrid app update:
diagrid app update <my-app> --archive-binding-name <my-binding> --archive-binding-type <my-archive-binding-type> --archive-completed --archive-failed
Once configured, executions are archived whenever they are purged or when a configured retention policy is applied. To stop archiving a state, pass =false to its flag on diagrid app update; to turn archiving off entirely, pass an empty value to --archive-binding-name.
See also
- Workflows concept — what workflows are and why to use them
- Durable execution — how history, replay, and determinism work
- Develop workflows — SDK guides and the orchestrator API per language
- Workflow patterns — orchestrator-side patterns including external events
- Workflow versioning — deploying code changes without breaking in-flight instances
- Workflow CLI —
diagrid workflowsubcommand reference - Operate — other day-2 administration topics
