Govern a lifecycle end to end
This walks a single-line approval chain onto an existing object, using the engine-owned three-layer workflow (instance / step / workitem).
This walks a single-line approval chain onto an existing object, using the engine-owned three-layer workflow (instance / step / workitem). Nothing is written to the customer table.
0. Prerequisites
- A project with the engine installed and
DATABASE_URLset. - The identity directory populated: node roles are resolved against
weavekit_user.roles, so users (and their roles) must exist. Seed them withweave sync:identity(see the identity guide), or insert rows directly for a quick trial.
1. Enable a starter chain
weave object:create order
weave workflow:open order --roles approverThis writes objects/order/workflow.json (a single review node, role approver, any-one mode) and
flips workflowEnabled in schema.json. Edit the file's nodes — for example an all-must-approve
finance step and a final manager step:
{
"nodes": [
{ "id": "finance", "name": { "en": "Finance" },
"assign": { "roles": ["finance"], "mode": "all" },
"onTimeout": { "after": "3d", "action": "reject" } },
{ "id": "manager", "name": { "en": "Manager" },
"assign": { "roles": ["manager"], "mode": "any" }, "onReject": "finance" }
]
}The engine infers the file format from nodes, so schemaVersion and the optional author version
can be omitted (the scaffold writes them for you).
2. Migrate
weave migratemigrate provisions the engine tables and content-addresses the definition. It never alters the
order table.
3. Run a record
Create a record and start the chain (as the originator):
POST /api/objects/order/<id>/workflow/submitThe instance is now running at finance; every finance user has an open workitem. Inspect:
GET /api/objects/order/<id>/workflow
# → { state: "running", node: "finance", actions: [...], workitems: [...] }- All-must-approve (
mode: "all") finishesfinanceonly after every finance user approves. - A reject rolls back to
onReject(herefinance; default would be the start node, where the originator edits in place and resubmits). A withdraw does the same but is initiated by the participant. - forward re-assigns an open workitem:
POST …/workflow/forwardwith{ "to": { "userId": "…" } }.
When the last node is approved the instance is finished and the record's mirrored status is
effective.
4. The caller's inbox
GET /api/workflow/todos
# → { items: [ { object, recordKey, workitemId, nodeId, ... } ] }5. Presence lock (UI)
While a participant has the record open, the UI holds a 60s lease so a concurrent withdraw/cancel is blocked:
POST /api/objects/order/<id>/workflow/lock # acquire / renew (heartbeat)
DELETE /api/objects/order/<id>/workflow/lock # on close6. Timeouts
finance above auto-rejects after 3 days. Enable the scheduler once:
// weavekit.config.ts
export default { subsystems: { workflow: { enabled: true } } };7. Admin re-activation
An admin (admin role) can re-open a terminal instance at any node — same pinned revision:
POST /api/objects/order/<id>/workflow/reactivate { "node": "manager" }8. History & audit
GET /api/objects/order/<id>/workflow/history returns the instance plus every step and workitem
(who acted, when, approval, comment, forwards). The audit trail records a transition event and the
live channel emits record.transitioned.
9. Evolve safely
Edit workflow.json (add nodes, change roles/modes) and run weave migrate. New records use the
new version; records already running keep executing the revision they started under. To roll new
records back onto a prior revision:
weave workflow:switch order --revision 1Remember: the object's own table is never touched — you can attach, evolve or remove a workflow without a migration on the customer schema.