Webform integration¶

orchestra_interaction_webform turns a Webform into a workflow touch point. A form can trigger a workflow (submitting it starts a run) and it can be a step the workflow reopens (collect more input, show a read-only review, or let someone edit an earlier submission). This page is the full configuration reference; for the concepts see External interaction.

What the module ships¶

A webform interaction plugin, chosen on a wait node's External interaction feature, so the node parks and dispatches the party to a form.
An Orchestra interaction Webform element (the "binding element"): one hidden field that ties a submission to a specific workflow step.
One Orchestra: start or resume on submit Webform handler.

The binding element¶

The binding element is a single hidden field (its own element type) that carries the workflow continuation handle. When the workflow parks a wait node and dispatches the party to the form, the interaction prepopulates this element with the handle for that step; on submit, the handler reads it to know which parked step to resume. On a fresh submission the element is empty, which is how the handler recognizes a first submission and starts a run instead.

When you need it¶

Add the binding element only when the form is reopened by the workflow as a step. Use this rule:

The form's role	Binding element?
Only triggers a workflow, never revisited	No
Reopened by the workflow as a step: collect, review, or edit/update the submission	Yes
Both (one form starts a run, then is reopened to modify)	Yes
Submission only ever changed by backend code, never through the form	No (for that update)

A trigger-only form needs no binding element: the handler treats "no binding element" as "every submission is a fresh start", and it binds the submission to the new instance itself (as the Webform source entity), so the submission is still linked to its run.

The element's value is a bearer continuation token, so it is stripped from any captured value map (see values_variable below) and never lands in a process variable.

The handler¶

There is a single handler, Orchestra: start or resume on submit, that does both jobs, keyed on the binding element:

No handle (empty or absent binding element) and a workflow is configured: the submission is a fresh start. It starts the workflow, binds the submission to the new instance as its source entity, and seeds the variables.
Handle present (the form was reopened by the workflow): the submission is a step. It resumes the bound instance's parked token with the configured outcome, and refreshes the submission id and value map.

Because one handler holds one set of settings, the start and resume sides cannot drift apart (for example capturing the value map on start but not on resume).

Settings¶

Setting	Applies to	Meaning
Start workflow	start	The workflow to start when a fresh submission completes. Leave as None for a form that only ever resumes a step.
Store submitter user id in variable	start	Optional process variable for the submitter's uid, so a step can route work back to the poster (the "By variable" assignment reads it).
Resume outcome (default `submitted`)	resume	The outcome the parked step is resumed with, for the outgoing flows to route on.
Submission id and values scope (`instance` or `token`)	resume	Whether the stored id and values are instance-wide or local to this branch. A start always seeds at instance scope.
Store submission id in variable	both	Optional process variable for this submission id, so a later step can address the exact submission.
Store submission values in variable	both	Optional process variable for the whole value map: seeded on start and refreshed on every resume (the modify loop), so a flow condition can route on a field and a step can read any answer.
Return to the workflow after submit	both	After starting or resuming, send the visitor to the workflow's next step instead of the webform's own confirmation (see Chaining). Off by default.

Configuring a webform¶

A form that only triggers a workflow¶

Build the Webform.
Add the handler and set Start workflow; optionally set the variables to seed.

No binding element needed.

A form the workflow reopens as a step¶

Build the Webform.
Add one Orchestra interaction (binding) element (its key is free; the handler and interaction find it by type).
Add the handler; set Resume outcome. Leave Start workflow as None if the form is resume-only.
On the wait node, set External interaction to Webform, pick the form, and choose the mode (below).

One form that both starts and is modified (the modify loop)¶

Add the binding element and the handler with both a Start workflow and a Resume outcome set. On the first (unbound) submission the handler starts the run; when the workflow later reopens the form for editing, the submission carries a handle and the same handler resumes it. Because it is one handler, the captured values_variable is seeded on the start and refreshed on every modify (each a resume), so the stored data always matches the latest submission.

Wait-node interaction modes¶

On the wait node's External interaction = Webform, the form renders in one of three modes:

Collect input (default): show the empty form to fill.
Review (read-only): render an existing submission as a read-only summary, for a step that inspects what was submitted without changing it.
Review (editable): reopen an existing submission for editing, for a step that revises it (the poster amending after a request for changes).

The review modes read the submission to show through a configured submission variable (the same variable the handler wrote the id into), so the right submission always reopens. A step can also display context: each context_display entry names a process variable (dotted paths reach into a structured value, e.g. validation.comment), a label and an optional severity (status, warning or error), and its current value is posted as a Drupal message wherever the step surfaces: on a review rendered in place, and on every page of the form the actor is redirected to. The value is read live from the instance each time, never stored into the submission, so a later viewer can never mistake an old note for the current one.

Chaining¶

By default a Webform shows its own confirmation page after submit. Turn on Return to the workflow after submit to instead send the visitor to the workflow's next step (the interaction dispatcher, or the inbox for a task), which is what lets one workflow chain several forms.

The handler disables this option for the inline and modal confirmation types, because those re-render the form in place instead of redirecting and would cancel the return. Set the form's confirmation type to one that redirects (for example Page) to use chaining.

Gotchas¶

Return to the workflow needs a redirecting confirmation type (not inline or modal), as above.
The binding element is required to reopen or edit a submission as a step. Without it a form can only ever start; a started submission is bound to its instance, but it cannot be reopened as a step.
A re-edit after the run has moved on resumes nothing. A stale submission can only ever complete the step it was bound to: if the branch looped back and re-parked on that same form step, the re-edit resumes the fresh token (the modify loop); if the branch is anywhere else, on a later step, finished, or merged, the submission is saved but nothing is resumed and no process variable changes.
A bearer submission cannot complete a step assigned to an operator. If the parked step declares assignments (an operator task), the handler refuses to resume it from a bearer webform submission: that step is completed only through the task route under the inbox's authorization check. The submission is saved but the run stays parked and no process variable changes, so a party holding a binding token cannot approve, or feed values into, the operator's step. The submitter is told so, and the refusal is logged: answers that were saved without completing anything are never reported as a success.

Worked example¶

orchestra_interaction_webform_examples wires all of this into a runnable request validation flow. Its Submission form carries the binding element and the single handler, configured with Start workflow request_validation, Resume outcome modified, and seeding request_sid (submission id), poster_uid (submitter), and request (the value map). The request_validation workflow forks a validate step (review, read-only) and, on a request for changes, a modify step (review, editable) routed back to the poster, who edits and resubmits. That editable step reopens the poster's own submission through Webform's secure token, which the form allows: editable review needs the form's Allow users to update a submission using a secure token setting on, and the step refuses to be configured against a form that does not have it. See the module's README for the full walkthrough.