Instance fields

An instance knows things its variables do not: who started it, its correlation key, when it started, its workflow, its label. A flow condition, an expression or a "by variable" audience reads variables only. The Instance field provider copies one of these fields into a variable, so they can read it too.

A message template needs none of this for most fields: it already has tokens such as [orchestra:label] and [orchestra:correlation-key] (see Tokens).

An example

An expense is approved by the requester's manager, whose user ID the starter passes as manager_uid. A manager filing their own expense would approve it themselves, so that case goes to the director instead. The start copies who started the instance into requester, and a step after it compares:

n_start:
  type: start
  features:
    variables:
      -
        plugin: instance_field
        settings:
          field: initiator
          variable: requester
n_check:
  type: passthrough
  features:
    variables:
      -
        plugin: expression
        settings:
          assignments:
            -
              name: self_approval
              expression: 'requester == manager_uid'

The flows after n_check route on self_approval. The Expressions provider ships in the optional orchestra_expression submodule.

The two rows are on two steps for a reason. The rows of one step all read the variables as they were before the step, and are written together after the last one ran. On one step, the expression would read no requester, and self_approval would be false for the manager too.

To offer a step back to the person who started the instance, no variable is needed: choose the Initiator audience (see Task assignment).

The fields

Field	What the variable holds
initiator	The user ID of the person who started the instance.
correlation_key	The instance's correlation key.
created	When the instance started, as a Unix timestamp.
workflow	The machine name of the instance's workflow.
label	What lists call the instance: its label, else its workflow's name.

A workflow's name can be translated. An instance given no label therefore writes its workflow's name in the language of the request that runs the step: the language of the page an action was taken on, or the site's default language when cron runs it. To show the label in a message, use the [orchestra:label] token instead, which also adds the instance's id. It is read as the message is rendered, so a private email shows it in its recipient's language (see Notification delivery).

Some instances have nobody to name as their initiator: one started by cron, for example, or a subprocess set to belong to nobody. For them, the initiator field writes nothing. The same goes for correlation_key on an instance with no correlation key. The variable then keeps the value it had, or stays absent, which an "is set" condition can tell.

A child workflow started as an instance of its own has its own fields. Its initiator is its parent's, the user acting when the step reached it, or nobody, as its step chooses (see Who the child instance belongs to). A child run inside the parent's instance (child_mode: embedded) has no instance of its own. Its steps read the parent instance's fields, the parent's workflow included.

Settings

• Field: one of the fields above.
• Variable: the variable it is written to. Choose a name that holds nothing else, such as requester. A name starting with two underscores is reserved for the engine and refused.

Like any computed variable, the value is written in the row's scope and shows in the instance's variable list and audit trail (see Variables).

A row written by hand in BPMN.io with no variable, a reserved one, or a field the provider does not know fails the step before anything is written. The step's incident says why.

When the starter already passes it

A starter that passes the same value under the same name is harmless: the row writes the field over it as the step starts. Keep the row anyway. It makes the step independent of whoever starts the instance, which is the point.