Action tasks¶

The optional Orchestra Action submodule (orchestra_action) adds an action task: an automated step whose work is a Drupal Action plugin. It is Orchestra's answer to Maestro's "batch function" task (a step that runs a named, automated operation rather than waiting for a human), built on Drupal's own action system instead of a bare function name.

Why an Action plugin, not a callable string¶

Maestro's batch task stores a PHP function name in configuration and calls it. Orchestra deliberately does not offer an arbitrary-callable field: a workflow is config (exportable, importable, shippable as a recipe), so a literal callable would turn "edit a workflow" into "run arbitrary PHP." A Drupal Action plugin is the safe, idiomatic equivalent: discoverable, configurable and access-aware, with its body in a plugin class. For logic that is purely about process flow, a custom task type remains the cleaner path, since it receives the token and instance directly.

The action task¶

A node of type action runs the configured action and then advances, with no parking and no inbox. Three kinds of action fit:

an entity action (one that names an entity type, like Publish or Delete) runs on a resolved target entity;
a system action (one with no entity type, like Send email) runs as-is;
a context-aware action (see below) is additionally handed the running process, so it can read and write process variables.

flowchart LR
  s([Start]) --> a["Notify owner<br/>type: action<br/>action: Send email"]
  a --> g{result?}
  g -->|success| d([Done])
  g -->|failure| r["Escalate<br/>type: action"]

Node config (in the Complete modeler or in YAML):

n_notify:
  type: action
  config:
    action_id: action_send_email_action
    action_settings:
      recipient: '[node:author:mail]'
      subject: 'Your article is in review'
      message: 'A reviewer will look at it shortly.'
    result_variable: notified
    result_scope: instance

action_id: the action plugin to run.
action_settings: the action's own configuration, when it has any (see Configuring the action).
result_variable / result_scope: see Success and failure.
target / target_variable: see Choosing the entity.

Choosing the entity¶

An entity action needs something to act on. Two sources, set by target:

attached (the default): the entity the process is bound to, via Orchestra Content's attachment. Requires that submodule.
variable: the entity whose ID is held in the process variable named by target_variable. The entity type is taken from the action.

A system action ignores target. If an entity action cannot resolve a target, the step fails (see below).

Success and failure¶

The step is automated, so it runs and the token advances. With a result_variable configured, the task catches a failing action and sets the variable to failure (and to success otherwise), so an outgoing flow condition can branch to an error path, the equivalent of Maestro's task completion status. Without a result variable, a failure propagates and fails the process (the engine's default), so a misconfiguration is never swallowed.

Configuring the action¶

When the chosen action has its own settings (a configurable action such as Send email), its settings form is embedded in the node editor. Because the modeler form has no live action switch, the settings reflect the saved action: pick an action and save, then reopen the node to configure its settings. A non-configurable action (Publish, Unpublish, Delete) needs none.

BPMN.io

In the diagram editor a node's properties are flat strings, so the action's nested settings are best edited in the accessible form modeler (orchestra_cm); action_id and the simple keys work in either.

Context-aware actions¶

A plain Action plugin's execute() receives only the entity, so it cannot reach the process. An action that needs the process (to read or write a variable, or to know which instance it runs in) implements Drupal\orchestra\OrchestraContextAwareInterface:

public function setProcessContext(ProcessInstanceInterface $instance, TokenInterface $token): void;

The action task injects the instance and token before running such an action, giving it the same reach a Maestro batch function has from its process and queue IDs. This interface lives in the kernel, so it is the general bridge for any foreign plugin Orchestra later runs as automated work; an action that needs no context simply does not implement it.

Relationship to the moderation task¶

The moderation_transition task is a special case of an action task: setting an entity's moderation state is one specific automated operation. The action task is the generic form: any action, on the attached or a named entity, with success/failure routing.