Variable Visibility — Data Associations in BPMN

The Principle

Stateway never exposes all process variables to the frontend. Only variables explicitly declared as inputs of a task reach the user. This is controlled by the process designer through Data Associations — a native BPMN 2.0 feature.

Why This Matters

A credit approval process may have variables like credit_score, internal_fraud_flag, and stripe_customer_id that are for internal process use and must not be shown to the user. With Data Associations, the designer declares exactly what each role sees — and Stateway guarantees nothing else passes to the frontend.

How to Declare

In any userTask, add Data Inputs and Data Outputs using your BPMN modeler's properties panel. Data Inputs are variables that arrive pre-filled in the form. Data Outputs are the variables the user produces when completing the task.

<bpmn:userTask id="approveTask" name="Approve Request">
  <bpmn:ioSpecification>
    <!-- What the approver sees -->
    <bpmn:dataInput id="in_amount"        name="amount" />
    <bpmn:dataInput id="in_justification" name="justification" />
    <bpmn:dataInput id="in_requester"     name="requesterName" />
    <!-- What the approver fills in -->
    <bpmn:dataOutput id="out_approved" name="approved" />
    <bpmn:dataOutput id="out_comment"  name="comment" />
  </bpmn:ioSpecification>
</bpmn:userTask>

The SDK will deliver only amount, justification, and requesterName in the work.snapshot event. Variables like creditScore or internalNotes will not reach the frontend even if they exist in the process.

When completing the task, the SDK only accepts approved and comment as outputs. Variables not declared in dataOutput are silently ignored.

Chaining Between Tasks

When one task produces variables that the next task needs to read, declare matching dataOutput and dataInput:

[Fill Form]                    [Review Form]
dataOutput: name, email        dataInput:  name, email, amount
            amount             dataOutput: approved, notes

The reviewer sees the data the requester filled in because those variables are declared as dataInput of the reviewer's task. Stateway resolves this automatically.

If No Data Input Is Declared

The task receives no pre-filled variables. The form renders blank. This is the secure default — the process designer is required to be explicit about what to expose.

variable_visibility: "all"

When the session scope declares "variable_visibility": "all", all process variables are delivered without filtering. Use this only in development and test environments.

{
  "scope": {
    "definitions": [...],
    "variable_visibility": "all"
  }
}