The Central Executive¶

The Central Executive (CE) is the first JATOS component in every 3C Platform study. It acts as the session controller, reading the study configuration, managing task flow, and handling interruption recovery — all before the participant sees any task content.

Keep the CE first

The Central Executive must always be the first component in the JATOS component list. Reordering or deleting it will prevent the study from running correctly.

URL parameters¶

The CE reads at least two parameters from the study URL when the session starts:

Parameter	Required	Values	Description
`UsageType`	Yes	`Predefined`, `UserChoice`, `ExperimentManager`	Controls how tasks are selected and sequenced. See Usage Types.
`Battery`	Yes	Integer	Index number that identifies which battery definition to load from `Batteries/Batteries.js`.

Example URL:

https://127.0.0.1/publix/8BexzI7alDM?UsageType=Predefined&Battery=123

The publix/8BexzI7alDM portion is the JATOS study run link, generated by JATOS when you create a study worker link. Replace it with the code shown in your JATOS interface.

Building the task list¶

When the CE loads, it:

Reads UsageType and Battery from the URL.
Looks up the battery entry with the matching index in Batteries.js.
Extracts the TaskList array — an ordered list of task objects, each specifying a Task (JATOS component name), Parameters (set of configuration parameters), and Instructions (set of instruction).
Resolves the parameters and instructions for each task by reading the corresponding configuration files.
Stores the resulting task list, parameter list, and instruction list in JATOS session data.

The CE then starts the first task by redirecting the JATOS session to the first component in the list.

Session data vs batch data¶

The CE uses two distinct JATOS storage mechanisms with different lifetimes and scopes. Their full descriptions are found at the JATOS website

Session data¶

Session data is temporary and lives only as long as the browser tab is open. The CE uses it to track:

The current task index (which task in the battery the participant is on)
The built task list, parameter list, and instruction list for the current session

When a participant closes their browser and reopens the study URL, the CE checks for existing session data. If found, it resumes from the last completed task index rather than restarting from the beginning.

Batch data¶

Batch data persists across sessions and is shared within a JATOS batch (a group of workers). The CE uses it to store:

Language preference — the language the participant selected via the on-screen dropdown. This persists so returning participants do not need to re-select their language.
BitIndex — used in Experiment Manager mode to track which phases of a longitudinal study have been completed.

Interruption recovery¶

If a participant's session is interrupted (browser closed, network drop, device timeout), their progress is not lost. When they reopen the same study URL:

The CE reads the JATOS batch data to find the last completed task index.
It resumes from the task immediately after the last completed one.
The participant's language preference is restored from batch data.

This recovery mechanism works for both Pre-defined and Experiment Manager modes. In User Choice mode, the participant always returns to the icon grid after each task, so recovery is handled automatically by that flow.

Session scope

Session data is tied to the browser tab and the JATOS worker. If a participant uses a different device or link, a new session starts from the beginning.

Completion behaviour¶

When all tasks in the battery are complete, the CE can:

Show a thank-you page — a configurable end-of-session message.
Redirect to a URL — the CE reads the Redirect field from the battery definition and sends the participant to that address. This is useful for redirecting participants to a recruitment portal or a debrief page.

Both options are configured in the battery definition in Batteries.js. If no redirect URL is provided, the study ends on the JATOS default end page.

Function reference¶

The CE is implemented in Batteries/CentralExecutive.js. Its functions fall into four groups.

Utility / data helpers¶

Function	Purpose
`isEmpty(obj)`	Returns `true` if an object has no own properties. Used to detect missing session or batch data.
`MakeIconList(TaskNameList, ComponentList)`	Builds an array of icon image filenames by matching each task name against the component list.

JATOS session and batch data¶

Function	Purpose
`CheckForSessiondata()`	Promise — checks whether JATOS session data exists and contains all expected keys. Resolves with a boolean.
`SetupBattery(SessionDataFlag, BatteryIndex, UsageType)`	Promise — if no session data exists, finds the battery by index, extracts task/parameter/instruction lists, and writes them into the JATOS study session.
`CheckBatchData()`	Promise — checks JATOS batch data for the current worker; initializes batch entries (index, language, bitIndex) on first visit, or restores the current index from batch on subsequent visits.
`UpdateSessionBitIndex(AddToCompletionCount)`	Promise — writes a completion bit value into the session data to track which session battery was selected and needs to be marked complete on finish.
`IsTheBatteryFinished()`	Returns `true` if `CurrentIndex` has reached the end of the task list, indicating the battery is done.

Function	Purpose
`StartComponent(title, data)`	Wrapper around `jatos.startComponentByTitle()` that launches the next JATOS component by title.
`UsageTypeDecision(UsageType)`	Promise — switches on usage type (`SingleTask`, `Battery`, `Session`, `UserChoice`) and routes accordingly — starting a component directly or pushing the appropriate jsPsych trial to the timeline.
`CentralExecutive()`	Main entry point. Promise — reads URL parameters, determines `UsageType`, checks for battery completion, then chains the setup promises and launches the appropriate next step.

jsPsych trial builders¶

Function	Purpose
`SetupjsPsychAndRunTimeline()`	Promise — initializes jsPsych and runs the global `timeline` array if it is non-empty.
`SetupSession()`	Reads session config parameters, builds button lists for the session manager page, checks completed bits from batch data, and returns the appropriate session button trial.
`MakeSessionButtonsNEW(...)`	Builds the session manager button trial for participants. On button press, sets up and starts the selected battery.
`MakeSessionButtonsLINKS(...)`	Same layout as `MakeSessionButtonsNEW`, but for staff use — each button assembles a direct JATOS participant URL and copies it to the clipboard instead of starting a battery.
`MakeUserChoiceElement(JATOSSessionData)`	Builds an icon-button trial letting the participant choose which task to run within a battery.
`MakeThankYouPage()`	Builds the end-of-study thank-you screen. Closes the window when the participant is done.
`MakeTestElement()`	Development/debugging stub — builds a minimal yes/no button trial.