Elements

Catalog of every element type with icons and short definitions

This page is a reference catalog. For deeper concept material, see Why Studyflow and Studyflow vs BPMN. For worked examples that use these elements in context, see:

• Cognitive tasks – CognitiveTask, timer events, trial-level structure.
• CONSORT – boundary error events, dropout handling.
• Data collection – questionnaires, parallel gateways, consent.
• Analysis pipelines – data operations, schemas, exclusive gateways.
• MLOps – snapshots, monitoring sub-processes, boundary events.
• Multi-agent collaboration – choreography.

The main element of a studyflow diagram is the Study, which serves as a container for all other elements:

Study represents the entire research project, including all the processes from experimental design to deployment and publication. It extends bpmn:Process and is the top-level container for all elements and workflows. Has runtime (cloud/local/hpc), authors, and the inherited isExecutable properties.

Within a Study element, you can define various elements. In addition to the standard BPMN elements, Studyflow introduces specialized elements for research workflows in cognitive sciences in four main categories: events, activities, gateways, and data. Every element also carries the core BaseElement documentation (markdown, stored as BPMN’s own documentation entries); a checklist is a studyflow:checklist-marked documentation entry, so its items stay visible in any BPMN tool.

Schemas

Studyflow elements ship in a layered set of moddle schemas:

• core (always loaded): Study, StartEvent, EndEvent, SequenceFlow, Activity, Arguments, plus the data-infrastructure types (Dataset, DataStorage, DataCatalog, Schema, Array, Snapshot).
• cognitive (always loaded): cognitive and behavioral elements (CognitiveTask, VideoGame, Rest, Questionnaire, Instruction, BehaverseTask, RandomGateway, EligibilityGateway, Actor). BehaverseTask (formerly the separate behaverse schema) is a CognitiveTask whose instrument is pinned to behaverse, delivered by the Behaverse Unity runtime.
• omniprocess, datatrove, openbci (optional): domain extensions enabled from the modeler’s schema palette.

See Extensions for the element catalogs of the optional extensions, and Authoring schemas for how to author your own schema.

Events

Start Event defines the beginning of the workflow. Optional consentFormUri (URL of a consent form) gates entry on informed consent at runtime; leave it unset to skip the consent step entirely.

End Event marks the conclusion of the workflow. Optional redirectTo URL redirects the participant on completion; supports {COMPLETION_CODE} placeholder. completionCodeType is none, static (fixed code), or dynamic (extracted from URL at runtime, e.g. Prolific).

Activities

Instructions display passive information (markdown content) to participants. Inherits from Questionnaire but uses an instruction instrument.

Questionnaires gather self-reported data. The instrument enum covers common standardized instruments (PHQ-9, GAD-7, BDI-II, STAI, PSS, WHO-5, BFI, DASS-21, PANAS) and accepts custom identifiers.

Cognitive Tasks deliver cognitive assessments. The instrument enum covers PsychoPy, jsPsych, lab.js, OpenSesame (and accepts custom IDs). configurations is instrument-specific YAML embedded in the diagram.

Video Games are interactive games used as experimental paradigms. instrument identifies the engine (e.g. unity, godot, web); configurations is engine-specific YAML.

Behaverse Tasks are standardized cognitive tests covering attentional, perceptual, cognitive, and motor abilities. See Behaverse assessment for the catalog. Provided by the optional behaverse schema.

Rest periods are intervals of inactivity or minimal activity, often used for baseline measurements, breaks, or resting-state recordings (e.g. resting EEG/fMRI). configurations holds e.g. duration and eyes-open/closed.

In addition, the abstract Arguments trait augments any BPMN activity with the arguments mapping. An activity’s inputs and outputs are not listed anywhere: they are detected from the data associations drawn on the canvas (connect a data element to a task and it is an input; the association’s parameter/result refine the binding). Whether a step is a data operation is derived the same way, not stored: it names a data verb (operationType) or runs software (implementation) without being a participant-facing instrument.

Gateways

Random Gateway randomly routes participants to one of the outgoing branches. algorithm is probabilistic or round-robin; probabilityFunction defines the distribution (default uniform).

Example use of Random Gateway to branch a flow.

Two additional gateways are provided by the cognitive schema (no dedicated icons – they render as exclusive gateways with distinguishing markers in the modeler):

• Stratified random assignment is a RandomGateway with stratifyBy set (e.g. age_band, sex, baseline_score): the cohort is partitioned by that variable and allocation runs independently within each stratum. Useful when the design requires balanced allocation across covariates; preset as the Stratified allocation palette template.
• EligibilityGateway – encodes inclusion/exclusion criteria. Participants meeting inclusionCriteria (and none of exclusionCriteria) proceed; others are routed to a screen-out branch. Criteria are markdown lists.

For control-flow gateways, Studyflow also uses standard BPMN gateways (ExclusiveGateway, ParallelGateway, InclusiveGateway).

Data

Dataset is a logical collection of data registered in a DataCatalog and stored in a DataStorage. Carries a format (BDM, BIDS, Psych-DS, Kedro), an optional schema, and format-specific properties (e.g. bidsDataType, bdmDataLevel).

Data Object represents data flowing through the process (a file, message, or stream). State annotations (e.g. [raw], [processed]) capture lifecycle.

The full data-element vocabulary (with definitions, attributes, and operations) lives in the dedicated Data reference:

• DataCatalog – persistent registry of datasets (e.g. openneuro, behaverse).
• DataStorage – persistent physical storage (database, filesystem, object store). Referenced via DataStoreReference.
• Schema – formal structure for a named collection of types (CSVW columns for tables; dimensions/types for arrays). Carries format and inline body.
• Array – multi-dimensional tensor (images, videos, fMRI). Expects a schema.
• Snapshot – immutable version of a dataset, table, or array. Carries source and version.

The current version of Studyflow includes built-in support for several data models commonly used in cognitive sciences:

Behaverse Events data model

Behaverse Trials data model

BDM Statistics & Models

Brain Imaging Data Structure

Psych-DS dataset standard

Kedro datasets

Element-to-schema mapping

Each visual element in the modeler maps to a type definition in one of the Studyflow moddle schemas under src/assets/schemas/:

• Event elements (StartEvent, EndEvent) live in core.moddle.yaml and extend the corresponding BPMN event types.
• Activity elements (Instruction, Questionnaire, CognitiveTask, VideoGame, Rest) live in cognitive.moddle.yaml and map to bpmn:Task with domain attributes shown in the inspector.
• Gateway elements (RandomGateway, EligibilityGateway) live in cognitive.moddle.yaml and map to bpmn:ExclusiveGateway.
• Data elements (Dataset, DataStorage, DataCatalog, Schema, Array, Snapshot) live in core.moddle.yaml; tabular and tensor structures map onto BPMN data references.