# Operate workflows

The Workflows page in the Catalyst console gives platform engineers and business operators a live view of the workflows in a project.

The sections below cover the console features that help in these scenarios:

- **Incident response.** A downstream service is failing. Find and pause the affected instances stuck retrying on that service, fix or scale the downstream system, then resume them.
- **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.
- **Routine housekeeping.** Long-running tenants accumulate completed instances. Periodically purge completed instances older than your retention window to keep listings responsive and storage bounded.
- **Unblocking a stuck approval.** A workflow has been waiting for an external event for days because the approver is unreachable. Find the affected instance and raise the event with the agreed payload to push the workflow forward without changing code.
- **Killing a bad batch.** A bug in an upstream system started workflows with malformed input. Filter the executions down to the affected ones, select them, and terminate them together rather than one at a time.

To manage workflows from the command line, see the [`diagrid workflow` subcommand reference](https://docs.diagrid.io/references/catalyst/cli-reference/workflow).

## Workflows list

The **Workflows** view shows a summary of the executions per workflow, including number of executions and an [execution status](https://docs.diagrid.io/concepts/workflows#lifecycle-states) breakdown.
Expanding a workflow entry in the list shows the detailed execution statistics by status.

![List of Workflow in a project with execution statistics](https://docs.diagrid.io/img/catalyst/wf-op-workflows.png)

### 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](#workflow-execution-details).

Selecting a node from the graph filters executions that executed this particular event.  This is useful for quickly finding workflows that ran a conditional activity, such as requesting approval or fraud analysis.

The filter dialog narrows the list further by the status of the selected node and the status of the execution. This allows, for example, filtering all running executions that failed in the "notify" activity.

![Workflow executions filter based on selected graph node](https://docs.diagrid.io/img/catalyst/wf-op-workflow-graph-filters.png)

You can run actions on each execution listed in the view. See [Workflow execution actions](#workflow-execution-actions) for the actions available.

![List of actions on a execution](https://docs.diagrid.io/img/catalyst/wf-op-workflow-actions.png)

### Sharing a filtered view

The workflow details view keeps its status and timespan filters in the address bar, so copying the URL captures what you are looking at. Paste the link into an incident channel and whoever opens it sees the same executions you do.

Filter by status with a repeated `status` parameter:

```text
/workflows/names/<appId>/<workflow>?status=failed
/workflows/names/<appId>/<workflow>?status=failed&status=terminated
```

The values are the ones the filter menu offers. A status the console does not recognize is dropped rather than passed on, so a mistyped link opens on every status instead of failing.

Set the time range either as a width or as explicit bounds:

```text
/workflows/names/<appId>/<workflow>?window=6h
/workflows/names/<appId>/<workflow>?from=2026-09-01T09:00:00Z&to=2026-09-01T17:00:00Z
```

`window` accepts `5m`, `30m`, `60m`, `6h`, `12h`, `24h`, `3d`, `7d`, or `all` for no time filter. Without a time parameter the view opens on the last 7 days.

A link needs both bounds, or one bound and a `window` to measure from it. A single bound on its own is ignored — resolving it would need a width from the reader's own settings, which would make the link show something different depending on who opened it. When `from` and `to` are both present, `window` is ignored.

## 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.

![Catalyst workflows console showing the list of workflow executions with their statuses](https://docs.diagrid.io/img/catalyst/wf-op-executions.png)

### Filtering workflow executions

The workflow executions list can be filtered by multiple criteria such as execution status, name, app, execution time, and others.

![Workflow execution filter selector](https://docs.diagrid.io/img/catalyst/wf-op-executions-filter.png)

![Workflow execution filtered by execution status](https://docs.diagrid.io/img/catalyst/wf-op-executions-filtered.png)

### Executing actions

You can run actions on each execution listed in the view. See [Workflow execution actions](#workflow-execution-actions) for the actions available.

![List of actions on a execution](https://docs.diagrid.io/img/catalyst/wf-op-executions-actions.png)

## Workflow execution details

Selecting a workflow execution displays the details of the execution: input, output and the history graph.

![Workflow execution graph](https://docs.diagrid.io/img/catalyst/wf-op-execution-graph.png)

### Graph node details

Selecting any node in the graph opens a details dialog. Selecting a failed activity, for example, shows its inputs, outputs and the error message, if any — in this case, a stack trace.

![Activity details with error stack trace](https://docs.diagrid.io/img/catalyst/wf-op-execution-activity-details.png)

### Event history

The **history** shows a step-by-step trace of the execution. This is useful for debugging workflow executions.

![Workflow execution history with event sequence](https://docs.diagrid.io/img/catalyst/wf-op-execution-history.png)

## Verify execution history

On a project created with [workflow verification](https://docs.diagrid.io/operate/platform-operations/projects#enable-verifiable-execution) 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](https://docs.diagrid.io/concepts/workflows#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**.

![Workflow execution header showing the History verified badge](https://docs.diagrid.io/img/catalyst/wf-op-verification-verified.png)

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.

![Verified execution graph with per-step verification seals and the Verification details summary](https://docs.diagrid.io/img/catalyst/wf-op-verification-graph.png)

### 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`:

![Workflow executions list flagging a tampered instance](https://docs.diagrid.io/img/catalyst/wf-op-verification-list.png)

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.

![Workflow execution detail showing a tampered history](https://docs.diagrid.io/img/catalyst/wf-op-verification-detail.png)

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:

![Event history of a tampered execution marking the events that failed verification](https://docs.diagrid.io/img/catalyst/wf-op-verification-history-tampered.png)

To verify from the CLI or produce portable proof an auditor can check offline, see [Verify workflow execution history](https://docs.diagrid.io/operate/project-operations/verify-workflow-history).

## Workflow execution actions

The action menu on each execution — in the [workflow details](#workflow-details) view and in the [all workflow executions view](#all-workflow-executions-view) — offers **Run new from**, **Suspend**, **Resume**, **Raise event**, **Terminate** and **Purge**.

Which of them you can use depends on the execution's [lifecycle state](https://docs.diagrid.io/concepts/workflows#lifecycle-states). 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 |
| **Purge** | Permanently deletes the execution and its history from the state store | Completed, Failed or Terminated |

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.

**Purge** carries two conditions the other actions do not. It needs delete access to workflows, where the rest need update access, so a role that can terminate an execution cannot necessarily purge one. And it is irreversible: the execution's input, output and full event history are deleted from the state store. Purge offers **Also apply to child workflows**, on by default. Purging from an execution's detail page returns you to the executions list, because the page you were on no longer exists.

### Acting on several executions at once

In the [workflow details](#workflow-details) view, the executions list has a checkbox on each row. Selecting one or more rows reveals **Suspend**, **Resume**, **Terminate** and **Purge** buttons that apply to the whole selection, so a filter followed by a select-all is how you act on a batch rather than an instance.

Filter first: the buttons act on what you have selected, and the same [lifecycle state](https://docs.diagrid.io/concepts/workflows#lifecycle-states) rules apply to each execution individually. An execution in a state the operation does not accept is reported back as a failure rather than silently skipped, and the executions that failed stay selected so you can retry them without picking them again.

Two differences from the single-execution actions:

- **Terminate** and **Purge** offer **Also apply to child workflows**, on by default. Clearing it acts only on the selected executions and leaves their children alone.
- **Suspend** and **Resume** require a reason, which is recorded against every execution in the selection.

**Raise event** has no bulk form — each event carries its own payload. Bulk actions are not offered on the [all workflow executions view](#all-workflow-executions-view), or on durable agent workflows.

The same operations are available from the CLI as [`diagrid workflow rerun`](https://docs.diagrid.io/references/catalyst/cli-reference/workflow/rerun), [`pause`](https://docs.diagrid.io/references/catalyst/cli-reference/workflow/pause), [`resume`](https://docs.diagrid.io/references/catalyst/cli-reference/workflow/resume), [`raise-event`](https://docs.diagrid.io/references/catalyst/cli-reference/workflow/raise-event), [`terminate`](https://docs.diagrid.io/references/catalyst/cli-reference/workflow/terminate) and [`purge`](https://docs.diagrid.io/references/catalyst/cli-reference/workflow/purge). Unlike the console, whose bulk actions act on the rows you have selected, `diagrid workflow purge` accepts `--bulk` to purge every execution matching a set of filters.

:::note Important
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:

```bash
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`:

```bash
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](https://docs.dapr.io/developing-applications/building-blocks/workflow/workflow-history-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`.

## Workflow notifications

Workflow notifications raise an alert the moment an execution reaches a state that requires your attention — a failed or stalled execution, for example.

Notifications can be visualized in the Catalyst console.

![Workflow notifications visualization](https://docs.diagrid.io/img/catalyst/wf-op-notifications-visualization.png)

Notifications are configured per app, and at least one state must be selected:

```bash
diagrid app create <my-app> --workflow-notifications-failed
```

| Flag | Raises an alert when an execution |
| --- | --- |
| `--workflow-notifications-failed` | Reaches the Failed terminal state |
| `--workflow-notifications-terminated` | Reaches the Terminated terminal state |
| `--workflow-notifications-stalled` | Becomes stalled — the runtime has stopped making progress on it, and the execution [offers no actions](#workflow-execution-actions) |

Completed executions cannot be selected. Notifications report the outcomes that need someone's attention.

Two more flags narrow which executions qualify:

- `--workflow-notifications-name` takes a regular expression that must match the **whole** workflow name. `order-.*` matches `order-fulfillment` but not `place-order-fulfillment`. Leave it unset to notify for every workflow.
- `--workflow-notifications-root-only` restricts notifications to executions with no parent, so one failing parent does not also raise an alert for each of its children.

Neither narrowing flag selects a state, so passing one without a state flag is rejected rather than accepted as a policy that would notify nothing.

To add or change notifications on an app that already exists, pass the same flags to `diagrid app update`:

```bash
diagrid app update <my-app> --workflow-notifications-name "billing-.*" --workflow-notifications-failed --workflow-notifications-root-only
```

Pass `=false` to a state flag to stop notifying on that state, leaving the rest of the configuration alone. Turning all three states off disables notifications for the app, which also clears the name pattern and the root-only restriction — so that combination cannot be passed together with `--workflow-notifications-name` or `--workflow-notifications-root-only=true`.

Each notification is raised as an alert on the app's project, labelled with the app ID, the execution id, the workflow name, the state that raised it, and the parent execution id when the workflow has one. Because the runtime reports an execution's state on every state save, the same outcome can be reported more than once; repeats carry the same alert and are collapsed rather than delivered again.

Raising an alert never holds up a workflow: a workflow's own progress does not depend on its notifications getting through. An alert the app cannot publish is dropped rather than retried.

## See also

- [Workflows concept](https://docs.diagrid.io/concepts/workflows) — what workflows are and why to use them
- [Durable execution](https://docs.diagrid.io/concepts/durable-execution) — how history, replay, and determinism work
- [Develop workflows](https://docs.diagrid.io/develop/workflows) — SDK guides and the orchestrator API per language
- [Workflow patterns](https://docs.diagrid.io/develop/workflows/patterns) — orchestrator-side patterns including external events
- [Workflow versioning](https://docs.diagrid.io/develop/workflows/versioning) — deploying code changes without breaking in-flight instances
- [Workflow CLI](https://docs.diagrid.io/references/catalyst/cli-reference/workflow) — `diagrid workflow` subcommand reference
- [App CLI](https://docs.diagrid.io/references/catalyst/cli-reference/app) — the `diagrid app create` and `diagrid app update` flags that configure archiving and notifications
- [Operate](https://docs.diagrid.io/operate) — other day-2 administration topics