Operating runs

ProWorkflow operations needs a JoobQ Pro key. Without one every Core feature keeps working: the Pro routes of the SDK gateway answer 402 pro_required and the console's Pro routes are not served. Get a licence · Core and Pro · Pro features index

These are console and API operations (/api/v1, roles in Roles and permissions); the SDK gateway has none of them. The server registers these routes only when it starts with a Pro key.

The Workflows page: registered workflows and their runs (mock data).

One run: the actions above, the step graph below (mock data). The Steps, Timeline, History and Payloads tabs show the same run in other forms.

Lifecycle

Route	Role	What it does
POST /api/v1/workflows/:id/cancel	operator	Cancels a running workflow, undoing the completed steps that can be undone
POST /api/v1/workflows/:id/terminate	operator	Ends a running workflow at once
POST /api/v1/workflows/:id/redrive	operator	Starts a new run (id <id>-redrive) from a failed, terminated, cancelled or timed-out one
POST /api/v1/workflows/:id/steps/:step/retry	operator	Retries a failed activity of a running workflow
POST /api/v1/workflows/bulk	operator	Terminates, cancels, signals or re-drives many workflows at once

A run that continued_as_new is a finished run: terminate, cancel and redrive refuse it with 409 naming its successor.

History and the archive

GET /api/v1/workflows/:id/history pages through a run's events. Finished runs are kept until JOOBQUI_WORKFLOW_RETENTION_DAYS prunes them; with JOOBQUI_WORKFLOW_ARCHIVE_DIR set they are written to the archive first (/api/v1/workflow-archive*). See Backups and retention.

Search attributes

Typed attributes (keyword, int, float, bool, time) that runs carry and the console searches by.

• Register a name: POST /api/v1/workflow-attributes {name, type} (admin), or JOOBQUI_WORKFLOW_ATTRIBUTES at start (name:type,name:type). The type is final and there is no removal; at most 100 names.
• Set them at start (search_attributes of POST /sdk/workflows or POST /workflows; at most 20 per run), from code (upsert_workflow_attributes), or from the console (POST /api/v1/workflows/:id/attributes, operator).
• Search: GET /api/v1/workflows with eq, range and prefix conditions (at most 8).
• A name that looks secret has its values hidden everywhere and cannot be searched. Audit rows hold names, never values.

Worker build ids (Crystal workers)

A joobq-pro worker started with JOOBQ_PRO_BUILD_ID names the code it carries and joins a compatibility set. A run is pinned to a set when it starts (the workflow's promoted default, or the build of the start), and only workers of that set run its activities. A pinned run whose set has no live worker waits. Promote, retire and re-pin (/api/v1/workflow-builds/:build/*, POST /api/v1/workflows/:id/repin) are admin: a re-pin states that the target build can carry the run's history, which the engine does not check. Retiring cannot be undone. Upgrade every process before the first promote or re-pin: older code cannot read the build_pinned event.

Crystal workflows: continue-as-new, updates, scopes, replay

The engine and the console support these for Crystal workflows (POST /api/v1/workflows/:id/continue-as-new, /updates/:name, /scopes/:scope/cancel, /replay, /migrate). SDK workflows declare scopes and update handlers in their blueprint (Scopes, updates and change gates) and use the same /updates/:name and /scopes/:scope/cancel routes.