Port definitions for the wagoe-workflow library.
Three protocols cover the full lifecycle:
IWorkflowStore — persistence of instances and audit log ITransactionalWorkflowStore — optional: a store on the caller's transaction IWorkflowEngine — high-level transition orchestration IWorkflowRegistry — in-process registry of workflow definitions
Port definitions for the wagoe-workflow library. Three protocols cover the full lifecycle: IWorkflowStore — persistence of instances and audit log ITransactionalWorkflowStore — optional: a store on the caller's transaction IWorkflowEngine — high-level transition orchestration IWorkflowRegistry — in-process registry of workflow definitions
Optional capability: a store that can join a caller's transaction. The
engine's tx arities need it.
Optional capability: a store that can join a caller's transaction. The engine's `tx` arities need it.
(store-in-tx this tx)This store, reading and writing on tx: an open transaction on the same
datasource. Throws :validation-error for anything else, a datasource
included, since that would autocommit.
This store, reading and writing on `tx`: an open transaction on the same datasource. Throws :validation-error for anything else, a datasource included, since that would autocommit.
Protocol for executing workflow transitions.
Protocol for executing workflow transitions.
(audit-log this instance-id)Return the audit log for a workflow instance.
Args: instance-id - UUID
Returns: Vector of AuditEntry maps, oldest first
Return the audit log for a workflow instance. Args: instance-id - UUID Returns: Vector of AuditEntry maps, oldest first
(available-transitions this instance-id actor-roles context)(available-transitions this tx instance-id actor-roles context)Return all transitions reachable from the current state, annotated with
:enabled? and, when blocked, a :reason keyword. With tx, as for
start-workflow!, the instance is read on it.
Runs full permission + guard checks for each reachable transition so UIs can render buttons as enabled or disabled accordingly.
Args: instance-id - UUID actor-roles - Collection of keywords (may be nil) context - Context map passed to guards (may be nil)
Returns: Vector of maps: {:id keyword :to keyword :label string? :enabled? boolean :reason keyword?} Empty vector when instance not found.
Return all transitions reachable from the current state, annotated with
:enabled? and, when blocked, a :reason keyword. With `tx`, as for
`start-workflow!`, the instance is read on it.
Runs full permission + guard checks for each reachable transition so UIs
can render buttons as enabled or disabled accordingly.
Args:
instance-id - UUID
actor-roles - Collection of keywords (may be nil)
context - Context map passed to guards (may be nil)
Returns:
Vector of maps:
{:id keyword :to keyword :label string? :enabled? boolean :reason keyword?}
Empty vector when instance not found.(current-state this instance-id)Return the current state keyword for a workflow instance.
Args: instance-id - UUID
Returns: Keyword or nil
Return the current state keyword for a workflow instance. Args: instance-id - UUID Returns: Keyword or nil
(process-auto-transitions! this workflow-id)Process all auto-transitions (:auto? true) for a workflow.
Finds every instance currently in a state that has an auto-transition and attempts to execute that transition. Intended to be called from a scheduled job (e.g. wagoe-jobs cron worker). With tenancy, in public and in every active tenant's schema.
Args: workflow-id - keyword
Returns: {:processed int ; transitions that succeeded :attempted int ; total instances considered :failed int ; transitions that were rejected or threw :failed-tenants int} ; with tenancy: tenants whose run failed
Process all auto-transitions (:auto? true) for a workflow.
Finds every instance currently in a state that has an auto-transition
and attempts to execute that transition. Intended to be called from a
scheduled job (e.g. wagoe-jobs cron worker). With tenancy, in public and
in every active tenant's schema.
Args:
workflow-id - keyword
Returns:
{:processed int ; transitions that succeeded
:attempted int ; total instances considered
:failed int ; transitions that were rejected or threw
:failed-tenants int} ; with tenancy: tenants whose run failed(start-workflow! this input)(start-workflow! this tx input)Create a new workflow instance in its initial state.
With tx, an open transaction on the store's datasource (a next.jdbc
connection or a platform transaction context), the instance is written on
it and commits or rolls back with the caller's own writes. A nil tx is
the same as none.
Args: input - WorkflowInstanceInput map: {:workflow-id :order-workflow :entity-type :order :entity-id #uuid "..." :metadata {}}
Returns: Created WorkflowInstance
Create a new workflow instance in its initial state.
With `tx`, an open transaction on the store's datasource (a next.jdbc
connection or a platform transaction context), the instance is written on
it and commits or rolls back with the caller's own writes. A nil `tx` is
the same as none.
Args:
input - WorkflowInstanceInput map:
{:workflow-id :order-workflow
:entity-type :order
:entity-id #uuid "..."
:metadata {}}
Returns:
Created WorkflowInstance(transition! this request)(transition! this tx request)Execute a workflow transition.
With tx, as for start-workflow!: the new state and its audit entry are
written on it. Hooks run before the caller commits, and side-effect jobs
join tx only when the job queue is transactional.
Args: request - TransitionRequest map: {:instance-id #uuid "..." :transition :ship :actor-id #uuid "..." :actor-roles [:admin] :context {}}
Returns: TransitionResult map: {:success? true :instance <updated WorkflowInstance> :audit-entry <AuditEntry>}
On failure: {:success? false :error {:type :forbidden :message "..."}}
Execute a workflow transition.
With `tx`, as for `start-workflow!`: the new state and its audit entry are
written on it. Hooks run before the caller commits, and side-effect jobs
join `tx` only when the job queue is transactional.
Args:
request - TransitionRequest map:
{:instance-id #uuid "..."
:transition :ship
:actor-id #uuid "..."
:actor-roles [:admin]
:context {}}
Returns:
TransitionResult map:
{:success? true
:instance <updated WorkflowInstance>
:audit-entry <AuditEntry>}
On failure:
{:success? false
:error {:type :forbidden :message "..."}}Protocol for managing workflow definitions at runtime.
Protocol for managing workflow definitions at runtime.
(get-workflow this workflow-id)Retrieve a registered workflow definition.
Args: workflow-id - keyword
Returns: WorkflowDefinition map or nil
Retrieve a registered workflow definition. Args: workflow-id - keyword Returns: WorkflowDefinition map or nil
(list-workflows this)List all registered workflow ids.
Returns: Vector of keyword ids
List all registered workflow ids. Returns: Vector of keyword ids
(register-workflow! this definition)Register a workflow definition.
Args: definition - WorkflowDefinition map
Returns: :workflow-id keyword
Register a workflow definition. Args: definition - WorkflowDefinition map Returns: :workflow-id keyword
Protocol for persisting workflow instances and their audit trail.
Protocol for persisting workflow instances and their audit trail.
(delete-instance! this instance-id)Delete an instance and its audit log, for an entity that is gone.
Returns: true when the instance existed
Delete an instance and its audit log, for an entity that is gone. Returns: true when the instance existed
(find-audit-log this instance-id)Return the full audit log for an instance, ordered chronologically.
Args: instance-id - UUID
Returns: Vector of AuditEntry maps
Return the full audit log for an instance, ordered chronologically. Args: instance-id - UUID Returns: Vector of AuditEntry maps
(find-instance this instance-id)Find a workflow instance by its id.
Args: instance-id - UUID
Returns: WorkflowInstance map or nil
Find a workflow instance by its id. Args: instance-id - UUID Returns: WorkflowInstance map or nil
(find-instance-by-entity this entity-type entity-id)Find the active workflow instance for a domain entity.
Args: entity-type - keyword (e.g. :order) entity-id - UUID
Returns: WorkflowInstance map or nil
Find the active workflow instance for a domain entity. Args: entity-type - keyword (e.g. :order) entity-id - UUID Returns: WorkflowInstance map or nil
(list-instances this opts)List workflow instances with optional filtering and pagination.
Args: opts - map with optional keys: :workflow-id - filter by workflow keyword :entity-type - filter by entity type keyword :entity-id - filter by entity id (UUID) :current-state - filter by current state keyword :sort, :dir - order by :workflow-id, :entity-type, :current-state, :created-at or :updated-at, :asc or :desc; a store may ignore them :limit - max results (default 50) :offset - pagination offset (default 0)
Returns: Vector of WorkflowInstance maps, newest first unless sorted
List workflow instances with optional filtering and pagination.
Args:
opts - map with optional keys:
:workflow-id - filter by workflow keyword
:entity-type - filter by entity type keyword
:entity-id - filter by entity id (UUID)
:current-state - filter by current state keyword
:sort, :dir - order by :workflow-id, :entity-type,
:current-state, :created-at or :updated-at,
:asc or :desc; a store may ignore them
:limit - max results (default 50)
:offset - pagination offset (default 0)
Returns:
Vector of WorkflowInstance maps, newest first unless sorted(save-audit-entry! this entry)Persist an immutable audit entry for a completed transition.
Args: entry - AuditEntry map (id already set by caller)
Returns: Saved AuditEntry
Persist an immutable audit entry for a completed transition. Args: entry - AuditEntry map (id already set by caller) Returns: Saved AuditEntry
(save-instance! this instance)Persist a new workflow instance.
Args: instance - WorkflowInstance map (id already set by caller)
Returns: Saved instance with server-side fields (created-at, updated-at)
Persist a new workflow instance. Args: instance - WorkflowInstance map (id already set by caller) Returns: Saved instance with server-side fields (created-at, updated-at)
(update-instance-state! this instance-id new-state)Update the current-state of an existing instance.
Args: instance-id - UUID new-state - keyword (must be a valid state in the workflow definition)
Returns: Updated WorkflowInstance
Update the current-state of an existing instance. Args: instance-id - UUID new-state - keyword (must be a valid state in the workflow definition) Returns: Updated WorkflowInstance
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |