| Title: | Process Orchestration Blocks for blockr |
|---|---|
| Description: | The organization as a data frame: process definitions, instances, and tasks live in one wide table that flows through a blockr board, in BPMN vocabulary throughout (process, task, lane, multi-instance, collection, element, assignee). A process block emits the table, task blocks write an append-only event log, a headless worker runs the tasks that are scripts, a file inbox lets other systems move a process forward, and a BPMN block renders the table as a standards-conform process diagram with live status painted on. The package is two layers in one namespace: the engine (table semantics, event store, worker, inbox) is pure R with no UI dependency, the blocks sit on top, and a test enforces the direction -- see 'dev/architecture.md'. The BPMN half (model, interchange XML, auto-layout, widget) lives in the 'bpmn-*.R' files and depends on nothing else here, so either layer can be lifted out into a package of its own once the process model stops moving. |
| Authors: | Christoph Sax [aut, cre] |
| Maintainer: | Christoph Sax <[email protected]> |
| License: | GPL (>= 3) |
| Version: | 0.2.1.9001 |
| Built: | 2026-11-19 08:15:15 UTC |
| Source: | https://github.com/cynkra/blockr.process |
The counterpart of [apply_assignments()]: same result shape, but the instance columns come from the store instead of from block state. Exported because the instance state block's expression calls it at evaluation time.
apply_events(df, store = ".runs", instance = "instance", stamp = NULL)apply_events(df, store = ".runs", instance = "instance", stamp = NULL)
df |
A wide process table (the definition). |
store |
Store directory. |
instance |
Instance id to filter by, or 'NULL' for all instances. |
stamp |
Poll counter (ignored). |
The wide table with 'assignee', 'due', 'status' and 'instance' applied.
The wide table is the "one table" convention: one row per process task, skeleton columns describing the task, optional instance columns ('assignee', 'due', 'status') describing a run. 'as_bpmn()' reads only the skeleton columns.
as_bpmn(df, name = "Process", external = NULL)as_bpmn(df, name = "Process", external = NULL)
df |
Data frame with at least 'task' and 'name' columns; 'role', 'depends_on', 'script', 'parent', 'collection', 'join', 'complete_when' and 'sequential' are used when present. |
name |
Process name. |
external |
Optional label of the external pool the inbox messages come from (e.g. '"Reporting unit"'). When set, every receive task ('role == "system"' without a script) gets a message flow from a collapsed pool of that name, so the diagram shows where the process touches the outside world. 'NULL' (the default) draws no pool. |
Conventions: - 'role == "system"' becomes a script task when 'script' is set, and a **receive task** when it is not: a system task without a script is completed by an inbox message (see 'vignette("external-systems")'), and the envelope marker says so. Any other non-empty role becomes a user task; empty role a plain task. - A row with a non-empty 'collection' is a **multi-instance sub-process** (see [process_groups()]), not work of its own: it is dropped from the diagram and the rows whose 'parent' names it are marked multi-instance instead, which is the '|||' marker on the activity. - 'depends_on' is comma-separated. A dependency may qualify the outcome it waits for: '"qacheck:true"'. The qualifier becomes the label on the arrow ('true'/'false' is the convention for binary checks). - A dependency may name a **container**, in either direction: '"each_g"' waits for the sub-process to complete, and a container's own 'depends_on' gates its members. Sequence flow may not cross a sub-process boundary in BPMN, so [process_body()] lowers container edges onto the members before anything else reads them (see there). - Start and end events are synthesized: tasks without dependencies hang off a start event, tasks nothing depends on flow into an end event. - Fan-in of more than one (non-loop) dependency synthesizes a join gateway. 'join' on the waiting row says which kind: 'all' (the default, a parallel gateway), 'any', or a quorum like 'n=3' / 'pct=90' (see [process_quorum()]). Loop-back edges (a dependency that is itself reachable from the task) stay direct arrows, so rework loops render as loops.
A [bpmn()] model.
A BPMN process model as two data frames: one row per node (events, tasks, gateways), one row per sequence flow (the arrows). This is the tidy counterpart of the semantic half of a BPMN 2.0 XML file. Layout (the "diagram interchange" half) is computed automatically and is never part of the model.
bpmn(nodes, flows, name = "Process", messages = NULL)bpmn(nodes, flows, name = "Process", messages = NULL)
nodes |
Data frame with columns 'id', 'name', 'type' and optionally 'lane', 'script' (what a script task runs, kept for round-tripping through [bpmn_to_table()]), 'multi' (logical: draw the activity as multi-instance, the '|||' marker) and 'multi_seq' (logical: that multi-instance runs its elements one at a time, BPMN 'isSequential', drawn as the '≡' marker). Recognized types (aliases in parentheses): 'startEvent' ('start'), 'endEvent' ('end'), 'task', 'userTask' ('user'), 'serviceTask' ('service'), 'scriptTask' ('script'), 'manualTask' ('manual'), 'sendTask' ('send'), 'receiveTask' ('receive', a task an incoming message completes), 'exclusiveGateway' ('gateway', 'xor'), 'parallelGateway' ('parallel', 'and'), 'inclusiveGateway' ('inclusive', 'or'), 'complexGateway' ('complex', the quorum join). |
flows |
Data frame with columns 'from', 'to' and optionally 'name' (the label on the arrow, e.g. a gateway condition). |
name |
Process name. |
messages |
Optional data frame with columns 'from' and 'to': message flows between the process and the outside world. Exactly one side of each row must be a node id; the other side is the label of an external pool (drawn collapsed), e.g. 'data.frame(from = "Reporting unit", to = "deliver")' for an incoming delivery. An optional 'name' column labels the flow. |
A 'bpmn' object: a list with 'nodes', 'flows', 'name' and 'messages' ('NULL' when there are none).
m <- bpmn( nodes = data.frame( id = c("a", "b", "c"), name = c("Start", "Do work", "Done"), type = c("start", "task", "end") ), flows = data.frame(from = c("a", "b"), to = c("b", "c")) ) mm <- bpmn( nodes = data.frame( id = c("a", "b", "c"), name = c("Start", "Do work", "Done"), type = c("start", "task", "end") ), flows = data.frame(from = c("a", "b"), to = c("b", "c")) ) m
The inverse of [as_bpmn()], so a process drawn in any BPMN tool becomes a table blockr.process can run: draw in Camunda Modeler, [read_bpmn()] the file, 'bpmn_to_table()' the model, drop the table into a process block.
bpmn_to_table(x)bpmn_to_table(x)
x |
A [bpmn()] model. |
What the inversion does: - Events and gateways disappear into the 'depends_on' grammar: a task behind a converging gateway depends on everything flowing into that gateway ('join' records the kind – exclusive/inclusive merge becomes '"any"', a complex gateway named '"k of n"' becomes '"n=k"'); a task behind a diverging gateway depends on the gateway's input, qualified by the branch label ('"validate:yes"'). Chains of gateways resolve through. - Lanes become 'role'; a lane-less script/service/send/receive task becomes 'role = "system"'. - Multi-instance activities are grouped back into containers: each connected run of multi-instance nodes gets a group row ('collection = "item"', a placeholder), its members point at it via 'parent', and edges crossing the group boundary are lifted onto the group row – the inverse of the lowering [as_bpmn()] performs.
The result is a **scaffold**, not a finished definition: fill in 'collection' names, check the quorums, and add 'script' values where the XML did not carry them (files written by [write_bpmn()] do).
A tibble with columns 'task', 'name', 'role', 'depends_on', 'script', 'collection', 'parent', 'join', 'sequential'.
[read_bpmn()], [as_bpmn()]
An htmlwidget: auto-layout (bpmn-auto-layout) and rendering (bpmn-visualization, Apache-2.0) both run in the browser, so no Node.js is needed for display. Pan and zoom are enabled.
bpmn_widget( x, status = NULL, overlays = NULL, width = "100%", height = NULL, elementId = NULL )bpmn_widget( x, status = NULL, overlays = NULL, width = "100%", height = NULL, elementId = NULL )
x |
A [bpmn()] model. |
status |
Optional named character vector/list: node id -> status. 'open', 'doing', 'blocked', 'skipped' get dedicated colours; any other value ('done', 'true', 'false', ...) is painted as finished. |
overlays |
Optional named character vector/list: node id -> small label rendered under the node (e.g. '"ana · 08-15"'). |
width, height
|
Widget size (CSS units). |
elementId |
Optional DOM id. |
An htmlwidget.
Shiny bindings for bpmn_widget
bpmnWidgetOutput(outputId, width = "100%", height = "420px") renderBpmnWidget(expr, env = parent.frame(), quoted = FALSE)bpmnWidgetOutput(outputId, width = "100%", height = "420px") renderBpmnWidget(expr, env = parent.frame(), quoted = FALSE)
outputId |
Output id. |
width, height
|
Widget size (CSS units). |
expr |
Expression returning a [bpmn_widget()]. |
env, quoted
|
Standard shiny render arguments. |
Produces the semantic half of a standard BPMN 2.0 interchange document (no diagram coordinates). Use [layout_bpmn()] or [write_bpmn()] to add auto-computed layout, or [bpmn_widget()] to render directly (layout then happens in the browser).
bpmn_xml(x, include_lanes = TRUE)bpmn_xml(x, include_lanes = TRUE)
x |
A [bpmn()] model. |
include_lanes |
Emit a 'laneSet' from the 'lane' column? Default 'TRUE'. Nodes without a lane (synthesized gateways, start/end events) inherit the lane of a neighbour, majority of predecessors first. The bundled auto-layout library (bpmn-auto-layout 1.3.0) drops all sequence-flow edges when a 'laneSet' is present, so the layout paths ([layout_bpmn()] and the widget) strip the lanes before laying out and band the result back into lanes afterwards. |
An 'xml2::xml_document'.
Recorded on every attempt as a 'code_version' event, so the log answers "what exactly ran here" a year later. The git commit of the jobs directory when it is a working tree, otherwise a content hash of the scripts – both are 8 hex characters, and neither claims more than "these bytes, that day".
code_version(jobs = ".")code_version(jobs = ".")
jobs |
Directory holding the scripts. |
An 8-character string, or '""' when the directory is unreadable.
The one-table convention mid-instance: skeleton columns ('task', 'name', 'role', 'depends_on', 'script') plus instance columns ('assignee', 'due', 'status'). The QA check has failed ('status = "false"'), so the reconciliation branch is active and approval waits.
example_process()example_process()
A data frame.
One row per (element, task) for multi-instance tasks, one row per task with ‘element = NA' for the rest. This is what the instance store’s events are folded onto and what the task lists show; the definition itself never grows.
expand_instance(process, elements = character(), instance = "instance")expand_instance(process, elements = character(), instance = "instance")
process |
A wide process table (the definition). |
elements |
Character vector of element ids (e.g. units), or a data frame whose first column holds them plus any grouping columns (e.g. 'region') to carry along. |
instance |
Instance id. |
A data frame with the definition columns plus 'instance', 'element' and the instance columns 'assignee', 'due', 'status'. The sub-process containers are gone – they are structure, not work – and each row carries its resolved dimension in 'per', so the expanded table answers "what does this repeat over" without the definition beside it.
The inbox directory of a store
inbox_dir(store = ".runs")inbox_dir(store = ".runs")
store |
Store directory. |
The path (not created).
Reads every '*.json' at the top level of the inbox in name order, applies the ones that make sense, and moves each file out of the way – 'processed/' when it was applied (or was a duplicate of one that was), 'failed/' with a '.error' file beside it when it can never apply. Messages for an instance that has not been started yet stay where they are: that is a race, not a mistake, and the next tick will get them.
ingest_inbox(store = ".runs", quiet = FALSE)ingest_inbox(store = ".runs", quiet = FALSE)
store |
Store directory. |
quiet |
Suppress messages. |
[run_worker()] calls this on every tick. Call it yourself from a cron job if your process has no scripts to run but does have an outside world.
The number of messages applied, invisibly.
store <- tempfile() process <- data.frame( task = "delivery", name = "Delivery", role = "system", depends_on = "" ) start_instance(process, instance = "2026Q1", store = store) write_inbox_message(store, "delivery", instance = "2026Q1", actor = "upload-platform", id = "d1") ingest_inbox(store, quiet = TRUE) instance_log(store, "2026Q1")[, c("task", "field", "value", "actor")]store <- tempfile() process <- data.frame( task = "delivery", name = "Delivery", role = "system", depends_on = "" ) start_instance(process, instance = "2026Q1", store = store) write_inbox_message(store, "delivery", instance = "2026Q1", actor = "upload-platform", id = "d1") ingest_inbox(store, quiet = TRUE) instance_log(store, "2026Q1")[, c("task", "field", "value", "actor")]
The element list an instance was opened with
instance_collection(store = ".runs", instance = "instance")instance_collection(store = ".runs", instance = "instance")
store |
Store directory. |
instance |
Instance id to filter by, or 'NULL' for all instances. |
A data frame (first column: element ids), or 'NULL'.
The definition an instance was opened with
instance_definition(store = ".runs", instance = "instance")instance_definition(store = ".runs", instance = "instance")
store |
Store directory. |
instance |
Instance id to filter by, or 'NULL' for all instances. |
The wide process table as stamped by [start_instance()], or 'NULL' if the instance has not been opened.
The only writer. Both the worker and the people write here, which is why 'actor' is recorded separately from 'assignee': 'assignee' is whose task it is, 'actor' is assignee moved it.
instance_event( task, field, value, actor = "worker", store = ".runs", instance = "instance", ts = format(Sys.time(), "%Y-%m-%dT%H:%M:%S"), element = NULL, ref = NULL )instance_event( task, field, value, actor = "worker", store = ".runs", instance = "instance", ts = format(Sys.time(), "%Y-%m-%dT%H:%M:%S"), element = NULL, ref = NULL )
task |
Task id. |
field |
Field the event sets: 'assignee', 'due', 'status', or any bookkeeping field the worker records ('log', 'took', 'attempt'). |
value |
New value. |
actor |
Assignee or what wrote this event. |
store |
Store directory. |
instance |
Instance id. |
ts |
Timestamp. |
element |
Element id for multi-instance tasks (the per-element rows, see [expand_instance()]); 'NULL' for single tasks. Written to the log only when set, so single-element stores stay byte-identical. |
ref |
Where this event came from, when it came from somewhere with a name: the inbox message file, a ticket id, a request id. Written only when set. 'actor' says which system spoke, 'ref' says which of its messages this was – together they make an event traceable back out of the process into the system that caused it. |
'value', invisibly.
Read an instance store's events
instance_events(store = ".runs", instance = NULL)instance_events(store = ".runs", instance = NULL)
store |
Store directory. |
instance |
Instance id to filter by, or 'NULL' for all instances. |
A data frame with columns 'ts', 'instance', 'task', 'field', 'value', 'actor', 'element' ('NA' for single-task events and old logs) and 'ref' ('NA' unless the event came in from a named message).
The instance id of the most recently opened instance ([start_instance()] order), or 'NULL' for a store without instances. The instance-reading blocks accept 'instance = "latest"' and resolve it through this on every poll – so opening a new instance moves the whole board to it, and the old instances stay in the log, addressable by their id.
instance_latest(store = ".runs")instance_latest(store = ".runs")
store |
Store directory. |
The audit view. ‘stamp' exists only so a polling block’s expression changes when the log grows; it is otherwise ignored.
instance_log(store = ".runs", instance = "instance", stamp = NULL)instance_log(store = ".runs", instance = "instance", stamp = NULL)
store |
Store directory. |
instance |
Instance id to filter by, or 'NULL' for all instances. |
stamp |
Poll counter (ignored). |
A data frame.
The multi-instance counterpart of [process_status()]. Stored status wins when it is anything but 'open'; for 'open' rows the gates decide, resolved per the three cases above. How many gates have to be met is the row's 'join' quorum, 'all' by default. Loop-back dependencies never block, same rule as the single-element case.
instance_status(process, instance_table)instance_status(process, instance_table)
process |
The definition (for gates, loops, 'join', 'complete_when' and the collection every task repeats over). |
instance_table |
An expanded instance table (see [expand_instance()]), carrying the current 'status' per row. |
Character vector, one entry per row of 'instance_table': 'open' (= ready), 'doing', 'blocked', 'skipped', or a terminal value.
[expand_instance()] over the stamped definition and elements, with the events folded on ([apply_events_instance()]). The 'status' column holds the STORED status; blocked/skipped are display states, see [instance_view()].
instance_table(store = ".runs", instance = "instance", stamp = NULL)instance_table(store = ".runs", instance = "instance", stamp = NULL)
store |
Store directory. |
instance |
Instance id to filter by, or 'NULL' for all instances. |
stamp |
Poll counter (ignored). |
The expanded instance table, or an empty data frame if the instance has not been opened.
[instance_table()] with the display status computed per row: stored terminal values stay, 'open' rows resolve to 'open'/'blocked'/'skipped' through the dependency gates ([instance_status()]). This is what the tasks block emits and what downstream tables and the BPMN overlay read.
instance_view(store = ".runs", instance = "instance", stamp = NULL)instance_view(store = ".runs", instance = "instance", stamp = NULL)
store |
Store directory. |
instance |
Instance id to filter by, or 'NULL' for all instances. |
stamp |
Poll counter (ignored). |
The expanded instance table with 'status' as display status.
Runs the bundled 'bpmn-auto-layout' library (via Node.js) to add BPMN diagram interchange (shape coordinates, edge waypoints) to the semantic XML, so the exported file opens with a proper diagram in any BPMN tool.
layout_bpmn(x)layout_bpmn(x)
x |
A [bpmn()] model or a BPMN XML string. |
BPMN XML (character) including 'BPMNDiagram' layout.
The skeleton brought to life: receives the wide process table, lets people assign 'assignee', 'due' and advance 'status' per task, and emits the table with the instance columns applied. Statuses 'blocked' and 'skipped' are computed from the dependency gates, never stored. Tasks whose outcome other tasks consume (checks) finish with an outcome label ('true'/'false' by convention) instead of 'done'.
new_assign_block(assignments = list(), ...)new_assign_block(assignments = list(), ...)
assignments |
Named list: task id -> 'list(assignee =, due =, status =)'. |
... |
Forwarded to [blockr.core::new_transform_block()]. |
The control UI is a JavaScript task list ('inst/js/assign-block.js'); R receives the assignments as JSON and turns them into an [apply_assignments()] expression.
'assignee' is a free-text field unless the incoming column is a **factor**, in which case its levels are the roster and the field becomes a picker. The allowed values are a property of the data, not of this block: declare them upstream with a stock mutate block, 'assignee = factor(NA_character_, levels = c("ana", "ben"))'.
Renders the incoming wide process table as a BPMN diagram (via the BPMN half: auto-layout + bpmn-visualization, no watermark) with the instance painted on: finished tasks green, 'doing' blue, computed 'blocked' amber and 'skipped' gray, and a 'assignee - due' overlay under assigned tasks. The data passes through unchanged, so downstream blocks (tables, dplyr views) keep working on the same table.
new_bpmn_block(title = "Process", ...)new_bpmn_block(title = "Process", ...)
title |
Process name shown in the exported BPMN. |
... |
Forwarded to [blockr.core::new_transform_block()]. |
An instance's events, newest first: the audit history. Nothing here is ever updated or deleted; the instance columns upstream are a fold over exactly these rows.
new_event_log_block(store = ".runs", instance = "instance", poll = 2, ...)new_event_log_block(store = ".runs", instance = "instance", poll = 2, ...)
store |
Instance store directory (see [instance_event()]). |
instance |
Instance id, or '"latest"' to follow the newest instance in the store. |
poll |
Poll interval in seconds. |
... |
Forwarded to [blockr.core::new_data_block()]. |
Design a process as a list of tasks: name, role, dependencies (with optional outcome qualifiers – pick "QA check · only true" to hang a task off one branch of a check) and, for 'system' tasks, the script to run. The block emits the wide process table; the diagram and the instance views downstream redraw as you edit.
new_process_block(tasks = example_tasks(), ...)new_process_block(tasks = example_tasks(), ...)
tasks |
List of tasks, each 'list(task =, name =, role =, dep =, script =, parent =, collection =)' where 'dep' is the comma-separated 'depends_on' string (outcome qualifiers as 'task:label'), 'collection' marks the row as a multi-instance sub-process and names what it repeats over, and 'parent' puts a task inside one. Defaults to the quarterly production example. |
... |
Forwarded to [blockr.core::new_data_block()]. |
The control UI is the outline rail ('blockr.outline::outline_rail_dep()') driven by a process adapter ('inst/js/process-block.js'): tasks are rows in flow order, dependencies are the rail drawn beside them, and the gestures are the board editor's – drag a task's dot onto another row to make it depend on it, release on empty canvas to append a task, hover a rail edge for the ✕.
The part of a process that repeats is a group: select the rows, press "Group them", and they sit inside a multi-instance sub-process whose header names the collection it runs once per. That frame is not a UI invention – it is how BPMN models a fan-out – and it is the only place the collection is named, so two tasks can no longer disagree about what the process repeats over.
Overlays an instance store onto the incoming process definition: the instance columns ('assignee', 'due', 'status') come from the append-only log, so the board shows what the worker and the people have actually done, live.
new_runstate_block(store = ".runs", instance = "instance", poll = 2, ...)new_runstate_block(store = ".runs", instance = "instance", poll = 2, ...)
store |
Instance store directory (see [instance_event()]). |
instance |
Instance id, or '"latest"' to follow the newest instance in the store. |
poll |
Poll interval in seconds. |
... |
Forwarded to [blockr.core::new_transform_block()]. |
Polling is on the log's size and mtime, so an idle board redraws nothing. The poll counter rides along in the block's expression as 'stamp', which is what makes the board re-evaluate when the log grows. A database-backed store would push instead.
Takes the process definition as its input and opens an instance from it: pick the year (the instance id), pick a collection, click "Start instance" – one [start_instance()]. Once the instance exists the card shows its header (id, [process_version()], created, size) and notes when the incoming definition no longer matches the stamped one.
new_start_instance_block( store = ".runs", instance = "instance", source = "", sources = list(), poll = 2, class = "start_instance_block", ctor = sys.parent(), ctor_pkg = NULL, ... )new_start_instance_block( store = ".runs", instance = "instance", source = "", sources = list(), poll = 2, class = "start_instance_block", ctor = sys.parent(), ctor_pkg = NULL, ... )
store |
Instance store directory (see [instance_event()]). |
instance |
Instance id. |
source |
Name of the selected element list. |
sources |
Named list of element lists: each a data frame (first column: element ids, e.g. units; further columns become the instance table's facets, an 'assignee' column seeds assignments) or a zero-argument function returning one (a ‘SELECT' on the platform’s database). Not serialized: a deployment wraps this constructor with its lists baked in and registers the wrapper. |
poll |
Poll interval in seconds. |
class |
Block S3 class. The wrapping constructor passes its own subclass (e.g. 'c("start_block", "start_instance_block")') so the registry keys on the wrapper. |
ctor, ctor_pkg
|
Forwarded to [blockr.core::new_transform_block()]; default: the CALLING constructor becomes the ctor of record, so its formals (‘store', 'instance', 'source', 'poll') define the block’s state. |
... |
Forwarded to [blockr.core::new_transform_block()]. |
The block emits [instance_view()], the expanded instance table.
This is a factory in the spirit of the JS-block factories: 'sources' holds data (or query functions) that cannot serialize, so a deployment MUST wrap it in its own constructor – with the lists baked in – and register that wrapper. See the demo's 'dcdemo::new_start_block()'.
An instance's task list: one section per task, one row per element for the "per-element" tasks, with per-row assignment and a status chip that writes [instance_event()]s. The toolbar filters (status, person, any grouping column the element list carried, e.g. 'region') and acts on the selection: bulk-assign.
new_tasks_block( store = ".runs", instance = "instance", poll = 2, roster = character(), ... )new_tasks_block( store = ".runs", instance = "instance", poll = 2, roster = character(), ... )
store |
Instance store directory (see [instance_event()]). |
instance |
Instance id, or '"latest"' to follow the newest instance in the store ([instance_latest()]): opening a new instance moves the list to it. |
poll |
Poll interval in seconds. |
roster |
Characters: the people assignments can pick from (the deployment's register). The definition's roles are NOT offered – roles are lanes, not persons; without a roster the block falls back to them so a bare demo stays usable. |
... |
Forwarded to [blockr.core::new_data_block()]. |
The block carries no action-specific gesture beyond that. "Send this back" is a decision, and decisions belong in the definition as outcomes: a dependent qualifies its predecessor ('fix depends_on review:rejected'), the chip then offers 'rejected' as a terminal state, and the branch is visible in the diagram instead of hidden in a button. Reopening a task that was already finished is one event from outside – [process_act()], an inbox message, a mirror – because the board is where open work is acted on, not where history is rewritten.
The block emits [instance_view()], so downstream tables and the BPMN diagram redraw on every event. Polling is on the log's size and mtime; an idle board redraws nothing.
The other writer of the instance store. This is exactly what the tasks block's status chip calls, and what a command line or an inbox message ends up calling: the worker cannot tell the difference.
process_act( task, status = "done", assignee = NULL, due = NULL, actor = NULL, store = ".runs", instance = "instance", process = NULL, element = NULL )process_act( task, status = "done", assignee = NULL, due = NULL, actor = NULL, store = ".runs", instance = "instance", process = NULL, element = NULL )
task |
Task id. |
status |
New status (‘doing', 'done', or a check’s outcome label). |
assignee |
Person the task is assigned to. |
due |
Deadline. |
actor |
Who wrote the event; defaults to 'assignee'. |
store |
Store directory. |
instance |
Instance id. |
process |
The definition, needed to re-arm loops. |
element |
Element id when the task is multi-instance; 'NULL' for single tasks. |
'status', invisibly.
The part of a process that repeats is a BPMN **multi-instance sub-process**, and under the one-table convention that sub-process is a row like any other: a row with a non-empty 'collection' is the group, and the rows whose 'parent' names it are its members. Each member runs once per element of the collection, and a task outside the group that depends on it waits for the whole sub-process to complete (the parallel join, see 'complete_when' for the quorum).
process_groups(df) process_scopes(df) process_collection(df) process_complete_when(df) process_sequential(df) process_body(df)process_groups(df) process_scopes(df) process_collection(df) process_complete_when(df) process_sequential(df) process_body(df)
df |
A wide process table. |
The value of 'collection' names the **collection type** the sub-process iterates ('unit'), not the concrete list: the definition is list-agnostic and the elements are bound when an instance starts. In Camunda's vocabulary the column therefore holds 'inputElement', while 'inputCollection' is instance data.
'process_groups()' lists the groups, 'process_collection()' answers the question every consumer actually asks – what does this task repeat over – and 'process_body()' drops the containers, leaving the rows that are real work.
Groups nest: a group whose 'parent' names another group repeats inside it. 'process_scopes()' gives the full enclosing chain, 'process_collection()' the innermost collection.
Tables written before groups existed marked every repeated task with a 'per' column instead; 'process_collection()' falls back to it when there is no 'collection' column, so old definitions (and the process JSON stamped into a running instance) keep folding.
BPMN forbids a sequence flow that crosses a sub-process boundary: the container carries the incoming and outgoing flows, its members are wired only among themselves. 'process_body()' is where that is turned back into a flat table, by *lowering* each container's edges onto its members, innermost group first:
- 'X depends_on G' becomes a dependency on every **leaf** member of 'G' (the members nothing else in 'G' waits for), which is the parallel join where the sub-process closes. - 'G depends_on Y' becomes a dependency of every **root** member of 'G' (the members that wait for nothing else in 'G') on 'Y', which is the fan-out where it opens.
A dependency that names a *member* from outside the group is left alone. It lowers to the same edge, which is why definitions written before containers were addressable keep working unchanged.
'process_groups()': a data frame with 'group', 'name', 'collection', 'parent' (the enclosing group, '""' at top level), 'complete_when' and 'sequential', one row per group.
'process_scopes()': a named list over every row of 'df' – the group ids enclosing that row, innermost first, 'character(0)' at top level. Errors on a 'parent' cycle.
'process_collection()': a named character vector over every row of 'df' – the collection that row repeats over, '""' for single tasks and for the group rows themselves. Nested groups resolve to the innermost.
'process_complete_when()': a named character vector over every row – the quorum spec of the group that row belongs to ('""' = all, and '""' for single tasks). This is what a task waiting on the group has to clear; see [process_quorum()] for the grammar.
'process_sequential()': a named logical vector over every row – whether the group that row belongs to runs its elements one at a time (BPMN 'isSequential'). 'FALSE' for single tasks.
'process_body()': 'df' without its group rows, with every container edge lowered onto the members (see details).
The worker runs files, not commands: the 'script' column of a process table names a file inside the jobs directory, and its extension picks the interpreter. Pass your own list to [run_worker()] to add one ('list(jl = list(command = "julia", args = character()))'); the names are lowercase extensions.
process_interpreters()process_interpreters()
'Rscript –vanilla' on purpose: a script that needs a package environment should say so itself ('renv::load()' on line one), so that what ran is visible in the script rather than in the worker's shell.
A named list of 'list(command, args)'.
Stored status wins when it is anything but 'open' ('doing', 'done', or an outcome label – any non-open value means the task has life). For 'open' tasks the gates decide: a gate whose dependency finished with the outcome it asked for is met, one that finished with another outcome never will be, and an unfinished one may still go either way. How many have to be met is the row's 'join' quorum, 'all' by default ([process_quorum()]). Loop-back dependencies never block.
process_status(df)process_status(df)
df |
A wide process table. |
Named character vector: task -> display status.
The machine-readable reading of the table that run UIs and status computation share: for every task its gates (non-loop dependencies with optional outcome label), loop-back dependencies, and the outcome labels other tasks consume from it (non-empty marks the task as a check).
process_tasks(df)process_tasks(df)
df |
A wide process table (see [as_bpmn()] for the conventions). |
A list (one element per task) of lists with 'task', 'name', 'role', 'script', 'per' (the collection it repeats over, '""' for single tasks), 'join' (the fan-in quorum spec), 'assignee', 'due', 'status', 'gates' (list of 'list(on, label)'), 'loops' (character), 'outcomes' (character). Multi-instance group rows are containers, not tasks, and are left out.
Polynomial rolling hash over the definition's cells; enough to tell two versions of a process apart in an audit line, not a cryptographic commitment. Deterministic across sessions.
process_version(process)process_version(process)
process |
A wide process table. |
An 8-character hex string.
The inverse of [bpmn_xml()]: parses the semantic half of a BPMN 2.0 interchange document – from this package, Camunda Modeler, bpmn.io or any other standards-conform tool – into a [bpmn()] model. Diagram coordinates are ignored (layout is always recomputed), namespace prefixes don't matter ('bpmn:', 'bpmn2:', none).
read_bpmn(x)read_bpmn(x)
x |
A path to a '.bpmn' file, a string of BPMN XML, or an 'xml2::xml_document'. |
What is read: the flow nodes [bpmn()] models (events, tasks, gateways), sequence flows with their labels, lanes, multi-instance markers ('isSequential' included), a '<script>' child on script tasks (the worker wiring [bpmn_xml()] writes), and message flows to or from collapsed pools. A file using elements outside that vocabulary (sub-processes, boundary or intermediate events, call activities) is refused with a list of the offending elements rather than silently flattened.
A [bpmn()] model. Pass it on to [bpmn_to_table()] to get a wide process-table scaffold blockr.process can run.
[bpmn_to_table()], [bpmn_xml()], [write_bpmn()]
The worker is a plain R process: start it from cron, a systemd unit, a Connect scheduled job or a second terminal. It holds no state of its own – everything it knows it read from the store, everything it did it wrote there – so killing it and starting it again loses nothing but the time in between.
run_worker( process, store = ".runs", instance = "instance", jobs = ".", wait = TRUE, tick = 2, timeout = 900, lock = TRUE, inbox = TRUE, interpreters = process_interpreters(), packages = character(), quiet = FALSE )run_worker( process, store = ".runs", instance = "instance", jobs = ".", wait = TRUE, tick = 2, timeout = 900, lock = TRUE, inbox = TRUE, interpreters = process_interpreters(), packages = character(), quiet = FALSE )
process |
A wide process table (the definition). |
store |
Instance store directory. |
instance |
Instance id, or '"latest"' for the newest instance in the store. |
jobs |
Directory holding the scripts named in the 'script' column. Scripts are resolved inside it and nowhere else. |
wait |
Poll for human events instead of returning at the first task a person owns. |
tick |
Poll interval in seconds. |
timeout |
Give up waiting after this many seconds. |
lock |
Take the worker lock, so a second worker on the same store refuses to start. |
inbox |
Ingest the file inbox on every tick. |
interpreters |
Extension -> interpreter map, see [process_interpreters()]. |
packages |
Packages whose functions a 'script' cell may name ('"mypkg::forecast"'). The allowlist for the function form, and the counterpart of 'jobs' for the file form: empty by default, so a deployment has to say which code it is willing to run. |
quiet |
Suppress progress messages. |
On every tick it ingests the inbox ([ingest_inbox()]), folds the log, and runs the ready tasks whose role is 'system' and which name a script. A ready task belonging to a person stops it (or, with 'wait = TRUE', it waits for that person's event).
The table with the instance applied, invisibly.
store <- tempfile() jobs <- tempfile() dir.create(jobs) writeLines("cat('hello\n')", file.path(jobs, "hello.R")) process <- data.frame( task = "greet", name = "Greet", role = "system", depends_on = "", script = "hello.R" ) run_worker(process, store = store, jobs = jobs, wait = FALSE, quiet = TRUE) instance_log(store, "instance")[, c("task", "field", "value")]store <- tempfile() jobs <- tempfile() dir.create(jobs) writeLines("cat('hello\n')", file.path(jobs, "hello.R")) process <- data.frame( task = "greet", name = "Greet", role = "system", depends_on = "", script = "hello.R" ) run_worker(process, store = store, jobs = jobs, wait = FALSE, quiet = TRUE) instance_log(store, "instance")[, c("task", "field", "value")]
Writes the '@instance' events that make an instance self-contained: the definition as opened (field 'process'), the element list (field 'elements'), the definition's [process_version()] (field 'version') and a 'created' mark. Everything after this moment is ordinary events on the instance's rows.
start_instance( process, elements = character(), instance = "instance", store = ".runs", actor = "board" )start_instance( process, elements = character(), instance = "instance", store = ".runs", actor = "board" )
process |
A wide process table (the definition). |
elements |
Character vector of element ids, or a data frame whose first column holds them plus grouping columns (e.g. 'region') carried into the instance table. An 'assignee' column seeds the assignment: every human multi-instance task of that element gets a 'assignee' event (actor 'register') – the "assignment comes from the register" answer. A list without the column leaves everything in the pool. |
instance |
Instance id (a period: "2026Q1", "2026"). |
store |
Store directory. |
actor |
Assignee opened the instance. |
The instance id, invisibly.
Reads the lock a running [run_worker()] holds and touches on every tick. A board can show it ("no worker is running, scripts will not start"), and a script that would rather ingest the inbox itself can ask first.
worker_alive(store = ".runs", stale = 120)worker_alive(store = ".runs", stale = 120)
store |
Store directory. |
stale |
Seconds without a heartbeat after which the answer is 'FALSE'. |
'TRUE' or 'FALSE'.
Write a tidy BPMN model to a .bpmn file
write_bpmn(x, path, layout = TRUE)write_bpmn(x, path, layout = TRUE)
x |
A [bpmn()] model. |
path |
Output file path (conventionally '.bpmn'). |
layout |
Add auto-computed diagram layout (needs Node.js)? If 'FALSE', only the semantic XML is written. |
'path', invisibly.
The R-side sender, useful from a scheduled script, a test, or a demo block standing in for a real platform. Any other language does the same thing by writing the same JSON: write to a temporary name in the same directory, then rename, so the ingester never sees a half-written file.
write_inbox_message( store = ".runs", task, value = "done", field = "status", element = NULL, instance = "latest", actor = "external", id = NULL )write_inbox_message( store = ".runs", task, value = "done", field = "status", element = NULL, instance = "latest", actor = "external", id = NULL )
store |
Store directory. |
task |
Task the message is about. |
value |
New value (default '"done"'). |
field |
Field it sets (default '"status"'). |
element |
Element id for a multi-instance task; 'NULL' for single tasks. |
instance |
Instance id, or '"latest"'. |
actor |
Who is speaking – the name of the sending system. It ends up in the audit trail, so use the system's name, not a person's. |
id |
Message id. Becomes the file name and is the idempotency key; defaults to a timestamped one. Give it a stable, meaningful id ('delivery-2026Q1-northside') and a resend is free. |
The path written, invisibly.
store <- tempfile() write_inbox_message(store, "delivery", element = "northside", actor = "upload-platform", id = "delivery-northside")store <- tempfile() write_inbox_message(store, "delivery", element = "northside", actor = "upload-platform", id = "delivery-northside")