4.5 Operating the catalog

Included from Basic tier

After this you can: operate the stored catalog from the operator's seat — definitions, versions, runs, gates, and the triggers and schedules that run them.

Before you start — tick each one:

• Lesson 4.2 — Store, browse, run (opschain learn 4.2)

In the GUI: the Workflows tab on a project page is the catalog; the Triggers and Scheduled activity tabs beside it are the automation that runs it.

Lessons 4.1 to 4.4 were the author's seat: write, store, drill the error paths, gate. This lesson is the operator's: you did not write these workflows, but you run them, answer their gates, read their history and keep the automation around them honest. The outcome is a short loop you can run on any project's catalog without opening a definition.

1. What a definition is, briefly

A workflow is YAML (or JSON): named steps, each running an action at a node scope, composed with stages and for_each fan-out. Expressions (${{ inputs.* }}, ${{ properties.* }}, ${{ steps.<name>.outputs.* }}) wire data between steps; on_error policy decides whether a scope absorbs or propagates a failure; a wait step parks the run for a human; governed sign-off is an approval policy holding the run before it starts (lesson 4.4). When you need the authoring model in full, opschain docs orchestration has it and opschain docs expressions the grammar — lesson 4.1 teaches it hands-on.

2. The catalog, and versions

Workflows live on the server as a versioned, per-project catalog:

opschain workflows list --project acme             # the catalog, archived ones included
opschain workflows show acme/<code>                # the summary: draft, archived, latest version
opschain workflows show acme/<code> --definition   # the authored YAML of the latest version
opschain workflows export acme/<code> --out f.yaml # round-trip the definition out
opschain workflows import acme -f f.yaml --update  # store a changed body as the next version
opschain workflows archive acme/<code>             # retire from the run surface; unarchive restores

Storing a changed definition never rewrites history: it creates a new version, and every run records the exact version it executed — a year-old run still shows the definition it actually ran, and runs create workflow … --version N runs any stored version on demand. Archiving retires a workflow from the run surface without deleting anything; it stays readable and its history intact, and unarchive restores it.

3. Running one, answering it, reading it

opschain runs create workflow acme/<code> --follow   # run the latest published version

created workflow 01a14510-…-example (<code> on acme) — pending
run 01a14510-…-example pending
run 01a14510-…-example pending → running
run 01a14510-…-example running → success

A workflow run is a run like any other: its steps show in runs show <run-id>, each nested change is attributable in runs list, runs logs <run-id> plays back every spawned run's lines, and the operator verbs are lesson 3.2's — runs continue|approve|reject <run-id> --step <step-id> for a parked step, runs retry, cancel, pause and resume for the run. A run held by an approval policy sits in pending_approval and is released from the approvals inbox (opschain learn governance-approvals), not from the step verbs.

4. The automation around it

Workflows are the usual target of automation, and an operator reads it in three places: a trigger creates a workflow run when an event matches its conditions, and opschain triggers firings <project>/<code> is its audit trail (lesson 5.2); a scheduled activity starts runs on a cadence, and opschain scheduled-activities list shows what is due next (lesson 5.3); steps can emit custom events for other triggers to react to (lesson 5.4). Whatever started a run, opschain chains show <correlation-id> reads the resulting cascade end to end — the run, every change it spawned, and the trigger decision that caused it (lesson 5.1). A workflow still named by a trigger or a scheduled activity cannot be destroyed (lesson 4.4): the reference is honoured both ways.

Check yourself

• Import a changed definition with --update: what does the output say was minted, and how do you run the previous version afterwards? Then name the two commands that tell you who or what has been starting this workflow without you.

What you learned

• The catalog is per project and versioned: list --project, show, export, import --update (a new version, never a rewrite), archive/unarchive.
• Every run records the version it executed, and --version N runs any stored one.
• A workflow run is operated with the ordinary run verbs; a policy hold is released from the approvals inbox.
• Triggers, scheduled activities and chains are where the operator reads what started a workflow and what it caused.

Next: this closes the module Workflows — back to your track (opschain learn).