Skip to content

gobpm Developer Manual

gobpm is an embeddable BPMN 2.0 process-execution engine for Go. This manual is the developer reference — the whole entity stack from foundation.BaseElement to the Thresher engine, the element taxonomies, how the runtime executes and processes events, how to control processes and instances, and how to extend the engine with your own implementations. Every page is grounded in the public API (go doc) and a runnable example; the why behind the design lives in docs/design/.

New here? Start with Your first process.

Part 1 — Getting started

Part 2 — Architecture & runtime

  • Architecture overview — the layer stack (model → snapshot → instance → engine) and how they relate.
  • The entity stack — BaseElement → Identifyer → flow node → activity/event/gateway → Process → snapshot → instance/track/token → Thresher. (pkg/model/foundation, pkg/model/flow)
  • Process, instance, track, token — how a definition becomes running work.
  • How a process executes — the run loop, node execution, the data phases (LoadData/Exec/UploadData/commit). (pkg/exec, pkg/renv)
  • How events are processed — the EventHub, waiters, correlation, delivery. (message-send-receive, signal-broadcast)
  • Scope & the data plane — where data lives and name resolution by walk-up. (process-data)
  • The engine (Thresher) — construction, configuration options, lifecycle (Run/Stop). (pkg/thresher)
  • Observability — facts, reporters, observers, the operator log. (pkg/observability, data-change)

Part 3 — The value & data model

  • The value model — Value and the four kinds (Collection/Record/Map); the tiers. (pkg/model/data, pkg/model/data/values)
  • Item definitions & item-aware elements — ItemDefinition, ItemAwareElement, Property, DataState. (pkg/model/data)
  • Reading & writing by path — records, lists, maps; assembling nested output. (structural-data, structural-output-mapping, maps)
  • Native Go structs — wrap your own types as live process data. (native-structs)
  • Expressions — conditions and computed values. (expression-routing)
  • Data Objects — scope-resident named containers. (process-data)
  • Data Store — engine-global cross-instance storage. (data-store)

Part 4 — Element reference

  • Foundation elements — BaseElement, Documentation, Identifyer, the shared attributes every element carries. (pkg/model/foundation)
  • Sequence flows — connecting nodes; flow.Link, conditions, defaults, and how a token traverses/splits at runtime. (pkg/model/flow)
  • Data associations — the data edge; AssociateSource/AssociateTarget, source/target routing, transformations. (pkg/model/data)

Tasks — Activities taxonomy (pkg/model/activities) - Service Task (service-task-worker) · User Task (usertask) · Script Task (script-task) · Business Rule Task (business-rule-task) · Send / Receive Task (message-send-receive) · Manual Task

Gateways — Gateways taxonomy (pkg/model/gateways) - Exclusive · Parallel · Inclusive · Complex · Event-based

Events — Events taxonomy (pkg/model/events) - Start & End · Timer · Message · Signal · Error · Escalation · Conditional · Link · Terminate · Compensation · Boundary events · Event sub-processes

Sub-processes & reuse — Composition taxonomy - Embedded Sub-Process · Call Activity · Transaction Sub-Process

Iteration — Iteration taxonomy - Standard Loop · Multi-Instance

Part 5 — Controlling processes & instances

  • Registering & versioning — RegisterProcess, versions, latest vs pinned. (versioning)
  • Starting instances — StartLatest/StartVersion, the instance handle. (basic-process)
  • Instance lifecycle — wait for completion, cancel, inspect state. (basic-process, terminate-end-event)
  • Observability in practice — subscribe, filter facts, tune the log level. (data-change)
  • Correlation & conversations — route messages to the right instance. (inter-instance-correlation, conversation-routing)
  • External workers — fetch-and-lock job execution. (service-task-worker)
  • Human tasks — the task distributor: list, assign, complete. (usertask)
  • Persistence & recovery — instance checkpoints, restart recovery, dehydration (a long wait costs no goroutines), and safely sharing one store between engines. (restart-recovery)

Part 6 — Extending gobpm

Each page: the seam interface, the registration call, a minimal real implementation, and how the engine uses it.

Part 7 — Reference