workflow

A guard takes one map and returns truthy (allow) or falsy (reject). Declare it under :guards in the workflow definition. The map holds:

A caller’s own :workflow/* context keys are dropped, so a request cannot forge either. A loader that throws fails the transition with an :internal-error; available-transitions shows the guarded transitions as unavailable and logs it. This guard refuses to deliver an invoice with no lines:

Guards passed to create-workflow-service apply to every workflow; a workflow’s own :guards win.

wagoe add workflow writes this under :active, and it is all the module needs:

The module wires its own database context and schema, and the job queue when :wagoe/jobs is enabled.

Every route requires authentication (session or bearer token) and answers 401 without it. The three reads and the start also need the :admin role or a :workflow/read grant from one of the caller’s groups, and answer 403 without either. If your application declares the permissions a group may grant, declare :workflow/read among them. A transition needs no grant: its :required-permissions decide.

In a multi-tenant application every route answers 403 to a caller outside the request’s tenant: not a member of it, not one of its users and not a platform admin. Without a tenant, only a user of no tenant is served. Inside a tenant, the admin that reads is the tenant’s: a platform admin, an admin by membership, or an admin user of that tenant; another tenant’s admin is not one. A grant counts there only when its scope names the tenant, {:tenant-id "<id>"}. The admin pages under /web/admin/workflows admit the tenant’s admins on the same terms, so a tenant admin sees their own tenant’s instances.

Bodies are kebab-case JSON, as in a scaffolded module’s API. Start an instance with:

A transition answers the instance and its audit entry. The instance carries the transitions available from its new state to the caller, as GET /instances/:id does:

A transition not enabled for the caller has "enabled": false and a reason: insufficient-permissions, or guard-rejected when a guard refuses it. One the workflow does not make from the current state answers 422:

An unknown instance is a 404 and a malformed body a 400, in the platform’s error shape.

To find an entity’s instance, look it up by the entity’s type and id:

It answers a list, one instance per workflow the entity is in, and [] for none. Both parameters are required. GET /instances/:id adds the available transitions.

available-transitions takes the instance id, the actor’s roles and the guard context. Each transition out of the current state comes back with :enabled?, and a :reason when it is false.

start-workflow! and transition! take an optional transaction before their input, so an entity and its workflow commit or roll back together. Pass an open transaction on the workflow store’s datasource: a next.jdbc connection or a platform with-transaction context.

A datasource is refused, since it would autocommit. A nil transaction writes on the platform transaction open on this thread on the store’s datasource, when there is one, else on the store’s own connection. Hooks run before the caller commits; side-effect jobs join the transaction only on the database job queue. Code inside a platform with-transaction without a handle on it can pass (wagoe.platform.database/current-transaction). Scaffolded entities do: a create and its workflow instance are written in one transaction.

With the tenant module on, each tenant schema has its own workflow_instances and workflow_audit. The tenant module runs workflow’s migrations in each tenant schema, the same series public runs, when it provisions a tenant and in every existing tenant schema at boot. A tenant request runs in a transaction bound to its schema, and the store reads and writes through that transaction, so a tenant reaches only its own instances. Outside a tenant, and in a single-tenant application, the tables in public are used as before.

Tenant work never falls back to public. A tenant schema without the tables, and tenant work outside a tenant transaction (on H2 under :allow-h2?, all of it), fail with a :configuration-error. Hooks run with the tenant bound, and side-effect jobs carry it in :metadata {:tenant-id …​}; with the tenant module on, job workers run such a job in the tenant’s schema, and fail it without one. A job for a queue outside the database is enqueued once the transaction commits, so a worker never sees a transition that may yet roll back. process-auto-transitions! runs in public and in every active tenant’s schema; its result counts tenants whose run failed under :failed-tenants.

Instances a tenant started before workflow was tenant-scoped are in public. Move each tenant’s rows into its schema, or they stay visible only outside any tenant.

A library ships tables of its own for tenant schemas by naming their migrations under :tenant-paths in its wagoe/migration-paths/<lib>.edn manifest. Those run only when the library’s module is switched on in :active.

workflow_instances.entity_id is text, because an entity need not be keyed by a UUID. Its generated, indexed entity_uuid column holds the same id as a UUID, or NULL when it is not one, so a UUID-keyed table joins it without a cast on PostgreSQL, H2 and SQLite alike:

An entity keyed by anything else joins on entity_id. migrate up adds the column, rewriting workflow_instances once on PostgreSQL. The boot adds it only in the dev, test and acc profiles; in any other it changes no table and logs a warning naming bb migrate up.