Multi-agent collaboration

Choreography for studies that involve interactions between participants

Experiments

Some studies cannot be described as a single participant walking through a flow – they involve interactions between multiple participants, or between a participant and an experimenter. BPMN2 introduced choreography tasks for exactly this. A choreography task is a specialized task that represents a sequence of interactions between participants: who initiates, what is sent, and in which direction.

Studyflow inherits BPMN2’s choreography construct unchanged. This page covers when and how to use it.

BPMN2 choreography elements include both tasks and the interactions between participants

BPMN2 choreography elements include both tasks and the interactions between participants

In the figure above, two participants – Subject and Experimenter – are involved in a study. In the first choreography task, the subject performs an activity called Give Consent. The same color is used for the task and the Subject band to indicate that the subject initiates the interaction.

When to use choreography

Choreography is the right construct when:

  • The study includes multiple participants (subject + experimenter, two-player game, parent + child).
  • The flow is driven by interactions between them rather than each participant’s internal steps.
  • You care about who initiates each interaction.

For single-participant studies, ordinary BPMN tasks and pools/lanes are simpler. Choreography earns its keep when the interaction itself is the unit of analysis.

In the modeler

The modeler ships a Choreography Task element (palette, under Activities). It is BPMN’s native bpmn:choreographyTask on the wire, so other BPMN tooling recognizes the element type as-is. It renders with the standard choreography notation: a participant band above and below the task name, with the initiating participant’s band drawn light and the other shaded. The bands are editable either in the inspector’s Participants tab or directly on the canvas by double-clicking a band (double-clicking the middle edits the task name, as usual).

Containment follows the BPMN 2.0 spec: a diagram made purely of interactions (choreography tasks, events, gateways) is saved under a bpmn:Choreography root, with the participants declared once and referenced per task via participantRef (top band first) and initiatingParticipantRef. Mixing choreography tasks into an ordinary process flow is also allowed – BPMN has no standard construct for that, so such diagrams keep the process containment and carry the participants as studyflow-namespaced attributes (topParticipant, bottomParticipant, initiator) instead. The bundled Dyadic decision study example (choreography_demo.studyflow) shows the spec-clean form in context.

Pattern: dyadic decision study

A common pattern: two participants take turns making decisions that depend on each other’s previous responses. Each round is a choreography task with one initiator and one responder. Across rounds, the initiator alternates.

A dyadic decision study: consent, then two decision rounds whose initiator alternates (light band = initiator). Rendered from the bundled choreography_demo.studyflow example.

A dyadic decision study: consent, then two decision rounds whose initiator alternates (light band = initiator). Rendered from the bundled choreography_demo.studyflow example.

The corresponding .studyflow file uses one ChoreographyTask activity per round, naming the two participants and which one initiates. See the Specification for the grammar.

Pattern: experimenter-driven protocol

When an experimenter administers a battery of tasks to a subject, you may not need full choreography – pools and lanes are usually enough. Use choreography only when the experimenter’s choice of what to do next depends on the subject’s responses during the interaction, not just before or after.

Pattern: parent-child or multi-generation

For developmental studies where the same data is collected from multiple family members, model each as a separate participant and use choreography for the joint tasks (e.g., parent administers a task while the child responds). Separate Start Events for parent and child indicate independent recruitment; choreography tasks tie the joint sessions together.

See also