Skip to content

Changing a variable

An administrator can set a variable in two places without writing code:

  • the Variables operation of a workflow, for the values every new instance starts with (Variables the definition declares);
  • the Edit link beside a variable on an instance's page, for the value an instance holds while it runs.

Both take a value the same way, as the incident Resume form does. An agent changes a running instance's variable with a tool.

How a value is typed

A value is typed as JSON when it is JSON, and as text otherwise:

You type The variable holds
6000 the number 6000
12.5 the number 12.5
"6000" the text 6000
approved the text approved
call back Monday the text call back Monday
true the boolean true
"true" the text true
["a", "b"] a list of two texts
{"city": "Bordeaux"} a structured value, read by a condition as address.city when the variable is address

So plain words need no quotes. Quotes are needed only for text that would otherwise read as something else: digits, true, false, null.

A value is always shown as JSON: text in quotes, a number bare. The instance page lists amount as "6000" when it holds the text and as 6000 when it holds the number. Saving a form without touching a value keeps its type.

The type is what the conditions that read the variable see, so a value meant as a number is best typed as one.

The values an instance starts with

Example: a claim workflow needs an amount to decide whether an expert review is offered (see Running a workflow as a case).

  1. Open Workflows, then the claim workflow's Variables operation.
  2. Type amount as the name and 6000 as the value.
  3. Save. Every instance started from now on begins with amount set to the number 6000, unless the code starting it passes its own.

The workflow stores the declaration in its configuration:

variables:
  - name: amount
    value: 6000

Changing a variable of a running instance

Example: the claim is running, and its amount turns out to be 25,000.

  1. Open the claim's page, from Instances.
  2. In the Variables table, click Edit beside amount.
  3. Type 25000 and save. The page says amount is now 25000.

What follows is what follows any write from outside a step:

  • the change is recorded in the audit trail;
  • the handlers waiting for a condition that reads amount are tested again. In the claim example, Request an expert review is offered, and Decide is withdrawn until the review has been requested.

The Edit link is offered only:

  • to a user with the Administer Orchestra permission;
  • while the instance runs. An ended instance reads its variables no more;
  • for an instance-wide variable. A variable local to one branch, listed with its step as scope, belongs to that branch;
  • for a variable of the workflow's own. The engine keeps its bookkeeping in variables named with __, and those are not changed by hand.

A value larger than 65,536 bytes, once encoded, is refused, as the HTTP API refuses it.

From code

The same change from code goes through the engine:

$engine = \Drupal::service('orchestra_engine.engine');
$instance = \Drupal::entityTypeManager()->getStorage('orchestra_instance')->load(492);
$engine->setVariable($instance, 'amount', 25000);

And from another site, through the HTTP API:

curl -X PUT https://example.com/orchestra-api/instance/492/variable/amount \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"value": 25000}'

The HTTP API refuses an instance that has ended, as the Edit link does.

A change made for a person carries the proof of who they are, and the person needs Administer Orchestra on the site that runs the engine, as for the Edit link:

{"value": 25000, "actor_proof": {"scheme": "asserted", "credential": "jean"}}

The scheme must be one that site granted the caller (see how the two sites identify the same person).

See Writing variables from code.

From an agent

An AI agent or an MCP client makes the same change with the orchestra_set_variable tool. The account it acts as needs the Access Orchestra tools and Administer Orchestra permissions. On a site running Orchestra Client, the remote Orchestra asks the same person for Administer Orchestra there too.

Example: an agent reading the claim's mail finds the corrected amount. It reads the claim with orchestra_get_instance, then calls:

{"instance_id": "492", "name": "amount", "value": 25000}

The value keeps its JSON type: 25000 is a number, "25000" a text. A null value is refused. What follows is what follows the Edit link: an entry in the audit trail, and the waiting handlers tested again.

From Drush:

drush tool:run orchestra_set_variable --uid=2 \
  --input='{"instance_id":"492","name":"amount","value":25000}'