TinyConductor 0.1.0

TinyConductor 0.1.0 is the first release of TinyConductor, a BPMN process engine. You draw a business process as a BPMN diagram, deploy it, and TinyConductor runs it: it starts process instances, hands work to your job workers and to people, evaluates DMN decisions, and waits for timers and messages. Every step is saved as a record that is never changed afterwards, so the console, the audit log and the analytics views can always show what happened and who did it.

TinyConductor is proprietary software. This release is a private beta, available under agreement. Read Beta data handling before you put real processes on it: during the beta, process variables must not hold personal data.

Three modes, one engine

The same engine runs in three deployment modes. A process behaves the same in all of them: the same path through the diagram, the same records, the same incidents and the same FEEL results. The modes differ in durability, speed, capacity and tenancy.

Mode	Use it for	How you run it
Embedded	Process tests and CI. Everything is in memory, with a virtual clock your test moves	The engine image, the tinyconductor program from the release download, or in-process from .NET or C through the Embedded library
Bundled	Demos, development and production for one team. The engine and its PostgreSQL in one container, on one volume	The Bundled image
Cluster	Shared production for many teams or customers (tenants), on a PostgreSQL database you operate, with several engine nodes sharing the work	The engine image, or the Helm chart on Kubernetes

Processes, decisions and forms

• BPMN. Service, user, send, receive, script, business rule and manual tasks, embedded and event subprocesses, call activities, multi-instance, gateways, and timer, message, signal, error, escalation, compensation, conditional and link events. Instances can be modified and migrated to a newer version. Not supported are the transaction sub-process, the complex gateway, loop markers and a few rare event kinds, as in the compatible engine. BPMN coverage rates every element, event and extension attribute.
• DMN and FEEL. Decision tables, literal expressions and requirements graphs, called from a business rule task or evaluated on their own. See DMN and FEEL.
• Forms. Forms are deployed with the process and shown to people when they work on a user task in the console.
• Script tasks in JavaScript, run by the separate script worker image. See Script tasks.
• Cluster variables, connectors and documents. See Cluster variables, Connectors and Documents.

API and client compatibility

TinyConductor serves a REST API in all three modes: a v1 API for existing clients and a v2 API, which is where new features go. Existing BPMN, DMN and form files, job workers, REST clients and connector runtimes written for the compatible engine work against TinyConductor without changes, as far as the elements and operations they use are supported. Job workers poll over REST; there is no gRPC endpoint.

Compatibility explains exactly what “compatible” means, which versions the engine is measured against, how to move an existing setup over, and where the behaviour is known to differ. The API reference in this documentation lists every operation.

Process tests run against the Embedded engine from .NET, Rust, C, Java, TypeScript, Python and Go. See Testing processes.

TinyConductor Console

The engine serves its own web application at /console, in every mode, with nothing to install. You sign in first, and the menu then shows only what your role lets you use. See Console.

• Operations. Instances and incidents with filters and shareable links; an instance’s page with its diagram, element timeline, variables and incidents; retry, cancel, modify and migrate one instance at a time.
• Tasks. People find, claim and complete their user tasks with the deployed form, save their own filters, and start processes.
• Decisions. Every deployed decision with its diagram and table, its requirements graph, a test evaluation, and past evaluations with their inputs, matched rules and output.
• Jobs. Find the work handed to job workers, see why a job failed and who holds it, and set its retries or complete, fail or throw an error from it.
• Cell health. Readiness, how quickly commands are confirmed, how far searches trail the engine, the nodes of the cell and their partitions, background work, and the busiest tenants.
• The Modeler. A full-screen workspace for processes, decisions and forms:
  • each open process, decision model and form in a tab of its own, and a task opens the form, decision or process it names;
  • the engine’s element templates applied to tasks, and its rules checked as you draw, with the problems listed beside the diagram;
  • deploy one model, or every changed tab together;
  • test runs: run the process as a real instance and follow it on the diagram, completing its tasks and jobs from a panel beside it; evaluate a decision and see the matched rules; preview a form exactly as people will see it. Test runs are left out of the instance and incident lists unless you ask for them.
• Administration. Tenants, users, groups, roles, API clients, mapping rules and grants, and the audit log.
• Analytics. Four reports, and views in PostgreSQL for your own reporting tools. See Analytics.

Tenants, identity and access

• Multi-tenancy. Each tenant’s processes, instances, history and settings are kept apart, with its own limits and history retention. In Cluster mode PostgreSQL also keeps the tenants’ rows apart. See Tenant quotas.
• Signing in. People sign in through your identity provider (OIDC) or as local users, or both. Programs use API clients that fetch short-lived tokens from the engine. See Identity and access.
• Who a person is. A person is the identity provider they sign in with and their id there, not their username. With more than one provider, each has a short alias, one is the default, and a username such as alice@corp names the person alice of the provider corp. A person the provider renames keeps their access and tasks, and a username given to someone new is refused until an administrator releases it. See Who a person is.
• Tenant administration (creating tenants, changing their limits, suspending them, naming their administrators) is possible only from the starting tenant, the installation’s own operator tenant. A tenant’s administrators manage their own tenant’s people and grants, never another tenant. See Who administers tenants.
• Export, import and purge of one tenant. A suspended tenant is exported to one checked file with everything it holds, imported from it on the same or another installation of the same version (under its own id or another one), and purged with everything it holds. See Exporting, importing and purging a tenant.
• Audit. The audit log records what was done and by whom, including changes to people, grants and tenants and refused requests. Each tenant’s entries are chained by fingerprints, and an integrity check tells you whether entries were changed or removed outside the engine. See Audit log.

History retention

Each tenant keeps its finished instances for its own history retention, 30 days unless you set another value; then the instance and everything about it is removed. Running instances are never affected. History is stored by day and removed a whole day at a time, so removing old history costs the database little and the disk space comes back right away; the database keeps up to one day more than the retention. See How long history is kept and Retention and disk.

Limits

• Request and model sizes. A request body is at most 4 MiB, a deployment 4 MiB and 100 files, and models are refused when they are nested deeper than the engine accepts. Larger requests are refused while they are read. See Request and model limits.
• Per tenant. Each tenant can have lower limits of its own: the size of a deployment, the variables one instance holds, and how many items one request carries, as well as quotas on running instances and request rates. See Tenant quotas.
• FEEL. An expression’s depth and the size of what it builds are bounded. See DMN and FEEL.

Running and monitoring

• Listening. The API and console listen on CONDUCTOR_SERVER_LISTEN_HOST (an IP address, 127.0.0.1 by default; the images set 0.0.0.0) and CONDUCTOR_SERVER_HTTP_PORT (8080). --bind host:port overrides both.
• Metrics. Bundled and Cluster serve GET /metrics on a port of their own, 9090 (CONDUCTOR_SERVER_METRICS_PORT), without a credential. Publish it only to your metrics scraper; on Kubernetes the chart’s network policy admits only the scraper’s namespace. See Scraping metrics.
• Health. GET /livez answers while the process runs and never reads the database, for the liveness probe. GET /readyz also needs PostgreSQL to answer within 2 seconds. GET /healthz returns the health report. See Health and readiness.
• Checking settings. tinyconductor config check reads every setting as a start would, without connecting anywhere, and prints a summary without secrets, or names the wrong setting and exits 1. An unknown CONDUCTOR_* variable is refused.
• Secrets from files. Every secret setting also takes a _FILE variant that names a file holding it, such as a mounted secret.
• Logs. CONDUCTOR_LOGGING_FORMAT chooses json or text, and CONDUCTOR_LOGGING_LEVEL the level. A JSON log line is flat: timestamp, level, message, tenant and trace_id are top-level fields.

Security

• Between Cluster nodes. Every request one node forwards to another is signed with the cell’s secret and cannot be replayed. The internal port has no default address: you choose a private one. Mutual TLS between the nodes is optional. See The internal port.
• Secrets at rest. The keys the engine signs its tokens with are stored encrypted in PostgreSQL. On its first start the Bundled image writes the secrets it generates (the first token and the administrator’s password) to a file only the engine can read, never to the log.
• The database. For a database on another host the engine checks PostgreSQL’s certificate and name over TLS by default; CONDUCTOR_STORAGE_TLS_ALLOW_UNVERIFIED turns that off where you must. The Bundled image never runs as root: it runs without capabilities, on a read-only root file system if you like, and keeps the engine in a kernel sandbox away from PostgreSQL’s files and the database superuser’s password, so the engine cannot act as the database superuser. The engine warns at start when its database login could bypass the tenant separation.
• Browser sessions. Over HTTPS the session cookies carry the __Host- prefix, so no other site, not even a sibling subdomain, can set them.
• Input. Requests, deployments, models, forms and FEEL expressions are checked against size and nesting limits before the engine works on them.

Measured performance

All figures were measured in one reference environment: a Linux virtual machine with 6 virtual CPUs and the engine’s PostgreSQL, described and measured on Hardware requirements.

• A process with one job, at 500 instances per second: the engine used about 0.4 cores and PostgreSQL about 1.2 cores, and creating an instance took 2.3 ms at the median and 6.2 ms at the 99th percentile, in Bundled and Cluster mode alike.
• Idle, a Bundled container needs about 54 MiB for the engine and 200 MiB in total; each running small instance adds about 12–17 KB of engine memory.
• Small finished instances take about 20 KB of disk each until the retention removes them.

Hardware requirements gives three starting sizes, and Performance and scaling the benchmark results with realistic processes.

Upgrading

This is the first release, so there is nothing to upgrade from.

From 0.1.0 on, the database is upgraded forward automatically when a newer version starts on the same database: back it up, stop the old version, and start the new one. In Cluster mode, stop every node of the cell first; rolling upgrades across nodes are not supported yet. See Upgrading.

If you tried a preview build

• Data is not carried over. The engine refuses to start on a volume or database written by a preview build and says how to reset it; see Bundled mode and How the engine runs your processes.
• Modeling is in the console. Processes, decisions and forms are edited in the console’s Modeler; there is no separate modeling page.

Known limits

• No batch operations. Cancelling, migrating or modifying process instances, and resolving incidents, is done one instance at a time.
• Little is deleted on request. Finished instances are removed by the history retention, not on request, and deployed processes, decisions and forms stay. A whole tenant can be purged, with everything it holds.
• Forms are checked in the console only. A task completed through the API is not checked against its form, so a job worker or client that completes tasks must send valid values itself. A few form components (such as HTML, images, tables, dynamic lists and file pickers) can be edited in the Modeler but are not shown in Tasks.
• Test runs. A test run can take a job only while no other instance in the tenant waits for a job of the same type, and in Bundled and Cluster mode its timers wait for their real time. The Modeler’s check runs in the browser; the engine checks the model again when you deploy it.
• Rolling upgrades across engine versions are not supported yet. See Kubernetes.
• Personal data. During the beta there is no way to erase personal data from the record stream; see Beta data handling.
• Starting through a root-level conditional start event is not supported yet; see Compatibility.
• Images and downloads are not signed; check each download against its .sha256 file. The .NET testing package is attached to the release, not published to a package feed.
• The Windows download is provided on a best-effort basis.

The pages linked above list further limits in detail, and Compatibility lists the differences in behaviour.

How to run it

Start with the Quickstart: one command runs the Bundled image, and five minutes later you have deployed the sample order process and completed a job.

You want	Use
Bundled mode	the registry.tinyfactory.ai/tinyblox/tinyconductor-bundled:0.1.0 image
The Embedded test engine, or Cluster nodes	the registry.tinyfactory.ai/tinyblox/tinyconductor:0.1.0 image, or the release download for your platform
In-process tests from .NET or C	the Embedded C library in the release download, and for .NET the TinyConductor.Testing.0.1.0.nupkg package file attached to the release
Script tasks	the registry.tinyfactory.ai/tinyblox/tinyconductor-script-worker:0.1.0 image
Kubernetes	the tinyconductor and tinyconductor-script-worker Helm charts attached to the release: tinyconductor-0.1.0.tgz and tinyconductor-script-worker-0.1.0.tgz
The sample process, the process-test projects and the monitoring files	the examples download, tinyconductor-0.1.0-examples.tar.gz

The release downloads (where to download them is given with your access):

Platform	Download
Linux x86_64	tinyconductor-0.1.0-linux-x86_64.tar.gz
Linux arm64	tinyconductor-0.1.0-linux-arm64.tar.gz
macOS arm64 (Apple silicon)	tinyconductor-0.1.0-macos-arm64.tar.gz
Windows x86_64	tinyconductor-0.1.0-windows-x86_64.zip

Each download holds the tinyconductor program, the Embedded C library and its header, a README and the third-party notices, and has a .sha256 file next to it. Check a download before you use it:

shasum -a 256 -c tinyconductor-0.1.0-linux-x86_64.tar.gz.sha256

Software bills of materials (CycloneDX and SPDX) for the engine, the script worker and the console are attached to the release as well.