Skip to content
DevLab

Protocols and their hierarchy

What Neurologyca publishes for your organization, what happens per person, and where microinterventions fit.

On this page
  1. The hierarchy
  2. If no context fits
  3. Catalogue and per person
  4. A protocol at a glance
  5. Measurement, as Engine returns it
  6. What you see in the API
  7. Reading the catalogue
  8. Positions and their clocks
  9. Steps, media and instructions
  10. Microinterventions
  11. Versions

Everything you capture hangs from a context that Neurologyca assigns to your organization. Inside it, a protocol says what is measured and when: an ordered list of positions, each one running a mechanic (the script of one capture) made of steps.

The hierarchy in two columns: the catalogue Neurologyca publishes and your data per person.

The catalogue

Published by Neurologyca. Immutable once published.

  1. Your organization

    Your organization in Engine.

    is assigned
  2. Context context

    A use case. It decides which protocols you can enrol people in.

    • not public Its rules may offer a mechanic as a microintervention after a capture.
    shares
  3. Protocol group protocol_group

    A family of protocols. It can be in several contexts.

    groups
  4. Protocol protocol

    What is measured, and how often.

    in order
  5. Position protocol_mechanic

    One slot of the protocol: its order and its schedule (when it can be captured).

    runs
  6. Mechanic mechanic

    The script of one capture.

    made of
  7. Steps step

    Each with its step_type, media and phases, plus the instructions.

Your data

Per person. You create it with the API.

  1. User

    A person in your application.

    • one per person Their baseline, shared by every protocol.
  2. Enrolment userProtocolId belongs to a protocol

    A person in a protocol. The enrolment belongs to a protocol in the catalogue.

  3. Capture of a position belongs to a position
    userProtocolId + protocolMechanicId

    What the person does in a position. The capture belongs to a position of the protocol.

    • optional Once it completes, Engine may raise: Interruption interruptionIdmicrointervention capture
  4. Results per step one per step

    The indicators of each captured step. There is one result per step.

Level (API name) What it is What it decides
context A use case your organization has been given Which protocols you can enrol people in, and whether captures can be interpreted
protocol_group A family of protocols; it can belong to more than one context What the interpretation focuses on
protocol What is measured, and how often Its positions, in order
protocol_mechanic (a position) One slot of the protocol When it can be captured: date, time of day and spacing
mechanic The script of one capture Its steps, fixed or free, and the screens shown between them
step (step_type) One stimulus or task Its type, suggested duration and what is shown

The whitepaper calls the mechanic a mechanism; the API says mechanic. You see a protocol if any of the contexts of its group is assigned to your organization. A protocol made for a single organization is seen and enrolled only by that one: for any other, it does not exist (404).

Your organization sees the contexts Neurologyca assigns to it, and the catalogue keeps growing. If none fits your case, you can commission one; to measure without a context, use Measurement.

Commission a context

If none fits, Neurologyca can build one for your case. Tell us what you want to understand, in which situation, and who the reading is for. Then:

  1. We start from the published literature on the topic and from what the capture can actually measure.
  2. We design the protocol and decide who the reading is for, and review it all with you.
  3. We assign it to your organization, and you integrate it like any other.

Always within responsible use: the reading is meant to support the person and must never be used on its own to decide about them.

Request a context at support@neurologyca.com, or talk to your Neurologyca contact.

Context Maker In development

A tool we are developing to create a context from your case. You will describe your case in your own words and it will propose a context: what to measure, how to ask the person and who to write the reading for, starting from the published literature on the topic and from what the capture can measure.

If part of what you are after cannot be measured yet, it will tell you so and suggest what you can measure instead.

You will also be able to ask Neurologyca to go over the proposal with you. A proposal does not create a context by itself: Neurologyca assigns it, like any other.

Neurologyca publishes it (catalogue) Happens per person (execution)
Context, protocol group, protocol, position, mechanic, step, media, instruction User, baseline, enrolment, the capture of a position, its results
The mechanics a context may offer as microinterventions (the rules that offer them are not public) An interruption (an offer that happened, anchored to the capture that triggered it) and its microintervention capture

You define nothing in the catalogue: you read it with GET /catalog/* and enrol people in it.

A synthetic example with three positions and one microintervention. Open a position to see its steps. Signed in with a team, you can switch it to one of your organization’s protocols: DevLab reads it from your catalogue, without creating users.

The Measurement protocol, from GET /user-protocols/{userProtocolId}/schema: one position, one step, any time.

You want to know Call
Your contexts and protocols GET /catalog/contexts, GET /catalog/protocols
The positions of an enrolment and which one is next GET /user-protocols/{userProtocolId}
The whole protocol, with schedules and scripts GET /user-protocols/{userProtocolId}/schema
The script of one position GET /user-protocols/{userProtocolId}/mechanics/{protocolMechanicId}
JSON
{
"order": 1,
"mechanic": {
"name": "Measurement",
"flowMode": "fixed",
"steps": [
{
"order": 1,
"type": "measurement_free",
"minTimeSeconds": 6,
"maxTimeSeconds": null,
"optional": false
}
]
}
}

Your backend reads the catalogue with your key (the browser SDK never calls these routes). Each one returns only what is assigned to your organization, ordered by id.

Route Returns
GET /catalog/contexts The contexts assigned to your organization: the themes that group your protocols
GET /catalog/protocol_group The protocol groups of your contexts, plus the group of the baseline protocol, which everyone has. That group arrives with interpreted: true today, but you enrol nobody in it and it is not interpreted by itself (see Baseline)
GET /catalog/protocols The protocols you can enrol people in; hasSchedule: true means it can only start at its first position, and interpreted: false that POST /analyze answers 409 PROTOCOL_NOT_ANALYSED (as with Measurement). Baseline is listed too, with interpreted: true, but you do not enrol people in it
GET /catalog/protocol_mechanic The positions of each protocol (which mechanic, in which order) with their three clocks
GET /catalog/mechanics The mechanics of your protocols and the microinterventions your contexts can offer, each with constellationSubcontextId (its analysis subcontext, or null)
GET /catalog/mechanics/{pid} One mechanic with its full script, for a microintervention your own app decides to offer
GET /catalog/mechanic_step Which step type, in which order, makes up each mechanic
GET /catalog/step_types The step types, with minTimeSeconds and maxTimeSeconds: the two ends of each response window. Several can share a type: current: true marks the one in use
GET /catalog/media The texts, images and videos of those step types
GET /catalog/step_type_media Which media goes with each step type

@neurologyca/capture-server reads six of them at once with listProtocolLibrary().

A position can declare three independent clocks; it is available where they overlap:

  • Date: a day counted from the first completed capture of the protocol (or a weekday), with a tolerance before and after. Once that window closes, the position is lost.
  • Time of day: windows in the person’s local time zone (the user’s timezone; without one, a default of the environment).
  • Spacing (timeBetweenSessionsSeconds): a minimum time since the previous capture. When clocks are enforced, Engine also keeps a minimum spacing between two captures of the same protocol, even when a position declares none; that minimum is a setting of the environment.

A protocol with hasSchedule: true declares a date or a time-of-day window for at least one position, and must be started at position 1. Spacing does not set hasSchedule and does not force the order. Engine declares these clocks and checks them when a capture is opened; whether a failed check rejects the capture or is only logged depends on the environment. Sessions, enrolments and interruptions shows the answers.

  • minTimeSeconds and maxTimeSeconds are guidance for your interface: Engine does not enforce them, and they are often null.
  • presentationSeconds, when present, says how long the step’s question is meant to be shown; the visualizer prints it as «shown N s». It is guidance too: the SDK gives it to you (PlanStep.presentationSeconds) and does not apply it.
  • media[] lists what can be shown in a step. When you show one, send its pid as mediaId with that step’s batches.
  • instructions[] are screens that are shown but not measured: beforeStep (with step) or atEnd.
  • An optional step may be skipped. A cyclic step (rounds, phases) is still one capture.
  • targetConstellationHciId names what the interpretation looks at in that step. The SDK gives it the same name, PlanStep.targetConstellationHciId.

A context may also define short mechanics that Engine can offer after a completed capture, such as a breathing exercise. They are not positions of your protocol: the offer arrives as an interruption of the capture that triggered it. See Sessions, enrolments and interruptions.

Published protocols never change: an edit creates a new version. An archived protocol can still be enrolled, with a protocolNotice that points to its replacement; a deprecated one accepts no new enrolments or captures.