Tokens

Orchestra registers an orchestra token type so any text rendered in the context of a running process can carry tokens that resolve against it. The first consumer is the message interaction body, where an author can greet a visitor by name, echo a reference number, or reflect a value the process carries. The same tokens are available to anything else that renders process text, such as notifications or audit messages.

The tokens are a capability of the engine, so they live in the base module and resolve wherever Orchestra is installed. They go through Drupal's standard token service, so global tokens ([site:name], [current-date:medium], and so on) work in the same text alongside the orchestra ones.

Available tokens

Following Drupal's convention ([node:type] is the machine name, [node:type-name] the human one), the bare token is the machine value and the -label variant is the human-readable one.

Token	Resolves to
[orchestra:var:NAME]	A process variable visible to the current branch, by name
[orchestra:instance-id]	The process instance id
[orchestra:workflow]	The workflow machine name
[orchestra:workflow-label]	The workflow label
[orchestra:status]	The status machine name (running, completed, cancelled, failed)
[orchestra:status-label]	The human-readable status (Running, Completed, …)
[orchestra:correlation-key]	The business reference key correlating the run, when set
[orchestra:created]	The date the instance started
[orchestra:token-id]	The current branch token id
[orchestra:node]	The machine name of the node the current branch sits on
[orchestra:node-label]	The label of that node
[orchestra:deadline]	The timer deadline on the current branch, when one is set

Variables and branch scoping

[orchestra:var:NAME] resolves a process variable as the current branch sees it. The engine layers a token's lineage over the instance-wide variables, so a branch-local value shadows the instance-wide one, and a name set only instance-wide resolves the same on every branch. This is the same view the flow conditions and the dispatcher use.

Internal bookkeeping variables (those with a double-underscore prefix) are not part of that view, so they never resolve as tokens.

Nested values

When a variable holds a structured value (an array), a dot-path reaches into it: [orchestra:var:validation.comment] resolves the comment key of the validation variable, and deeper paths (a.b.c) work the same way. A path that does not resolve to a scalar leaves the token to clear.

Chaining into a referenced entity

When a variable holds an entity id, name the target entity type and chain that type's own tokens onto it: [orchestra:var:NAME:ENTITY_TYPE:CHAIN]. For example [orchestra:var:validator_uid:user:display-name] loads the user whose id is in validator_uid and renders its [user:display-name], and [orchestra:var:node_id:node:title] renders a referenced node's title. The entity type is explicit in the token, never guessed; an id that does not load or a value that is not a scalar leaves the token to clear.

Like core's own entity tokens, chaining does not apply an entity or field view-access check: it resolves the field regardless of who the rendered text is later shown to (that is the point, for example when a message shown to the poster names the validator). Because the chain type and property are fixed by the workflow author (who holds administer orchestra), only a field the author chose is ever surfaced. Still, treat it as a disclosure: only chain fields that are safe to show to everyone the message can reach. Do not chain a sensitive field (a private profile field, an unpublished entity's data) into a message whose audience should not see it.

The instance-scoped tokens (workflow, status, correlation key, created) resolve from the instance alone. The branch-scoped tokens (the current node, the deadline) resolve only when a branch is in context, since a "current node" is a property of a branch, not the whole instance. The node's label is read from the workflow version the instance is pinned to, so it matches the run even after the live workflow is edited.

Date formats

The date tokens accept any Drupal date format by chaining it on, exactly as core date tokens do:

• [orchestra:created:medium]
• [orchestra:created:long]
• [orchestra:created:custom:Y-m-d]
• [orchestra:deadline:short]

The bare [orchestra:created] uses the medium format.

Discovering tokens

When the contrib Token module is installed, the message interaction form shows a token browser listing the orchestra group and every global token, so an author can insert one without memorizing the names. The replacement itself does not need that module: it uses the core token service, which is always present.

Safety

A variable value is inserted as data, not markup: token replacement escapes each value, so a value an author cannot control (a visitor-supplied variable, say) cannot inject markup into the page. In the message interaction the result is then filtered as admin HTML, so the author's own formatting is kept while unsafe markup is stripped.

Using the tokens in your own code

To render text with these tokens from a module, pass the instance under the orchestra data key and, for the branch-scoped tokens, the branch token under orchestra_token:

$text = \Drupal::token()->replace($authored_text, [
  'orchestra' => $instance,
  'orchestra_token' => $token,
], ['clear' => TRUE]);

Pass a \Drupal\Core\Render\BubbleableMetadata as the fifth argument and apply it to your render array so the cache metadata the tokens carry (a dependency on the instance, its workflow and the branch) is not lost. Omit orchestra_token when there is no branch in context; the branch-scoped tokens then resolve to nothing and the instance-scoped ones still work.