Exception management

When a validation or transform fails, you choose whether the run records a normal audit error or a durable exception you can triage later. Exceptions are distinct from canvas audit Warnings and Errors: they persist on the workflow and appear on Exception Management (?view=exceptions).

On error configuration

On an operation badge (and on node execution settings) you set On error:

raise error - existing audit error path for the run
raise exception - writes an audit row with reserved type exception, then the workflow engine syncs that row into Exception Management when the run finishes

You also set exception type (label), message, and severity (operator levels 1-5). The default exception type for an operation is {action} {type} issue (for example arrayLengthLessThan validation issue). For a node without an operation context, the default is {nodeType} issue.

Exception Management views

Open the workflow Exception Management tab (View → Exceptions) to triage persisted exceptions for that workflow. Named views live on the workflow (table, board, list, calendar, timeline). You can create, rename, duplicate, reorder, and delete views. Each view has its own layout plus which properties it shows, and its own filter, sort, and group. Use the sliders control on the toolbar for view settings (layout, property visibility, filter, sort, group, and header stat tiles) and Exception Management property schema in one menu. In Property visibility, drag a property by its grip, type icon, or name to reorder columns for that view. Hide stays a separate control. Your last-selected tab is personal to you; it is not shared with the team.

The Exceptions view icon shows a count pill for active open exceptions and uses the colour of the worst open severity. That wash and count stay visible while Exception Management is the selected view. Severity colour comes from ticket levels 1-5. The pill shows 9+ when more than nine tickets are open.

Table

The default table is one row per ticket. Columns follow that view’s shown properties. You can wrap cells, freeze leading columns, resize data columns (including Status, Assignee, and Severity), and edit writable properties inline. Select and Actions stay a fixed width. Use the leading Select checkbox to pick rows on the current page. When two or more rows are selected, a compact Selection strip appears on the view toolbar with a Bulk Edit menu (aggregate property fields and per-bucket moves), configurable quick action chips, and a clear control. Actions include View (opens the Exception panel), Resolve, and Close.

Board

A board groups cards by a status, select, or people property. Drag a card between columns to update that property on the ticket. If the view has no group property yet, the board asks you to pick one. Column headers can add, rename, recolour, and reorder options for status and select properties.

List

A list is a compact vertical list: title plus shown properties. You can optionally group rows; group headers collapse.

Calendar and timeline

A calendar places tickets on a month grid by a date property you choose (Calendar by). Days without a date go to an Unscheduled tray. A timeline places a bar from a start date to an optional end date (Timeline by), with day, week, and month zoom. If the date binding is missing, the view opens and asks you to pick the date property.

Exception panel

On Exception Management the workflow right toolbar shows Triggers, Audit log, and Developer Tools. Overview, Nodes, Operations, and Data Query stay off that rail. Exception and AI Chat stay off the rail on every view. Header AI Chat (sparkles) opens as its own column to the right of Exception instead of replacing it. Until you resize AI Chat, it matches the tools sidebar width. Home, Knowledge Graph, and Admin Header AI stay a single dock.

In the table, click Message, Type, or another surface cell (not Status, Assignee, or Severity) to select that ticket and open the Exception panel, including when the panel pin is released. Tick the row checkbox to open the same panel; two or more checkboxes switch it to bulk mode with a count in the header. Status, Assignee, and Severity stay dropdowns so you can change those fields without opening the dock.

On board, list, calendar, or timeline, click a card, row, chip, or bar to select the ticket. The Exception panel opens when it is pinned (the default). Unpin keeps those card clicks from opening the panel; View in Actions still opens it.

For one ticket, the panel shows schema-visible properties (system, origin, and custom) in schema order, excluding rows you mark default hidden in All Properties, plus Comments (append-only GitHub Flavored Markdown via Add comment; History renders that source) and History (status, severity, assignee, and comments). Comment rows show the commenter on the timeline (user, agent, or agent with a user badge). Captions read Comment added by the operator, or Comment added by the agent on behalf of the operator. Use Collapse and Expand on the History heading to switch compact density. Each History change is also recorded in the Activity log. Quick actions in the panel header come from Exception Management settings (defaults include Resolve and Close) plus Show on canvas.

For multiple tickets, Properties show aggregate rows: a count pill beside each value (always the number of selected tickets with that value, never ALL). Click a value to facet-filter the other properties. You can select more than one value in the same property. Values that no longer match stay visible at count 0, greyed out, and not clickable. Header quick actions run the same presets with an all suffix (for example Resolve all), skipping tickets where that action is disabled. Bulk property editing for checkbox selection also lives in the view-toolbar Bulk Edit menu; the panel does not show History in bulk mode.

Message is the raised exception text; it does not change when you add a comment. Enable the read-only Last comment system property in view settings when you want the newest comment body in table, board, or filters. Lineage stays on canvas Overview.

Resolve and Close update the ticket’s status option (defaults include Raised, Investigating, Awaiting review, Resolved, Closed, plus options you add in Exception Management settings). Assignee is a member of the workflow team (or the owner on a personal workflow). Unassigned cells show a dash. Assignment is stored on the ticket and survives reload. If that person later leaves the team, the cell still shows their name; the picker lists current members plus Unassigned only.

Properties and origin rows

Exception Management settings manage typed properties (text, number, select, status, date, people, checkbox, url, email). System fields (message, status, assignee, severity, type, identity keys) stay first-class. Originating-row snapshot keys appear as origin properties you can type, show, and order.

Columns that come from a ticket’s stored originating-row snapshot keep a Status-coloured left accent on the raising field. Presence (active / inactive) is machine-owned. Status is yours.

When the first Schema on a lineage defines a row identity key, live runs match the same ticket by that key:

A new key inserts a ticket.
A key still raising this run updates the snapshot and leaves the Status you set.
A key missing from this run’s exception set becomes inactive. It stays in its Status with an inactive mark. Resolved plus inactive stays in Resolved.
If that key raises again, the same ticket becomes active and keeps your Status.

The first run after you define a Schema key does not rematch older tickets that used a full-row content hash; those become inactive and current-run exceptions insert as new tickets.

Open Exception Ticket Persistence from Community Templates (Financial) to walk this loop on a five-row trade blotter keyed by tradeId. Quantity and notional validations raise exceptions. You can Resolve a ticket, edit or delete that trade in Static Data, and re-run to see the same ticket stay, become inactive, or reactivate with the Status you set.

Agent tools

When you assign the Workflow capability on an agent, that agent can list, read, and update Exception Management tickets, and can change that workflow’s Exception Management properties and views. Pass the Convex workflowId from chat User context JSON. Access follows workflow read and write permission; these tools are not gated by data-query or workflow-config chat flags.

When an agent schedule fires on exception_raised or exception_status_changed, User context includes selection.exceptionIds and exception.exceptions for every ticket in that batch. A run that raises many tickets starts one turn.

When you select one or more tickets in Exception Management (open ticket or table checkboxes), new AI chats on that workflow also receive selection.exceptionIds. The AI Chat composer shows a chip with each ticket’s message (not the document id). Hover the chip for Chat context: plus the kind and full message. Use workflow_getException with each id.

Tool	What the agent can do
`workflow_listExceptions`	Bounded summaries (default 25 tickets, maximum 100) with optional filters for status, node, type, and severity. Each row includes the status option id and display name. The list does not return originating-row snapshots.
`workflow_getException`	One ticket, property values (the Actions column is table chrome and is omitted), append-only comments, history, and the workflow’s status options. Pass both `workflowId` and `exceptionId`. A mismatch or missing read access returns empty.
`workflow_updateException`	Writable ticket fields: status option (id or name), severity 1-5, assignee (Convex user id or null), custom properties, and an optional append-only comment. Unknown statuses are rejected with the available options. Only this ticket changes.
`workflow_getExceptionManagement`	The workflow’s Exception Management properties, named views, and assignee pool. Use this before you change setup.
`workflow_updateExceptionManagement`	Ordered edits to properties and views (add, rename, retype, delete, reorder, configure show/filter/sort/groupBy). You cannot delete system properties or the last view.

See Tools and MCP for how you assign built-in tools.

Activity log - exception changes alongside every other tracked change, with the same views
Workflow orchestration - pipeline model and execution engine
Operation node - transforms and validations on rows
Schema node - row identity key that Exception Management uses to match tickets across runs
Tools and MCP - built-in workflow_* exception tools on the Workflow capability tile