Skip to main content

Sequences

A sequence is what a participant opens and works through in one sitting: an ordered list of pages, each holding atoms. It sits in the tenant's library until a journey, a member of staff or the participant themselves assigns it, which makes a user sequence. Written once, it serves every assignment.

Pages​

  • Every write needs at least one page, and every page at least one atom, or it is refused with sequence_incomplete, draft or not.
  • A page or atom whose condition hides it is dropped, and the pages renumber. A page left with nothing visible is skipped, so a five-page sequence can run as two pages for one person. Conditions here read the answers given so far in the same sitting (atomResponses.<atom>.current; see Conditions).
  • Leave one unconditional atom on a page that carries conditional ones. Just after the app starts, some of what a condition reads may not have loaded, and a page of only conditional atoms can come up empty.
  • advanceOnResponse moves the page on by itself once its single choice is made, after a short pause. A required choice then hides the forward button; an optional one, a date or a typed field keeps it. On a page with a multi-select or more than one input (a button counts) it does nothing.
  • A start button shows on the home screen only when startButtonLabel is set. Without it the item shows the automatic to-do mark.

Tags​

A sequence carries any number of its tenant's tags, as tagIds, from the same list people are tagged from.

  • They are content, published with the version. A changed set reaches participants and journeys once the sequence is published, and each version keeps the set it had.
  • listSequences?tagIds= lists the sequences carrying any of the tags given.
  • In an export file they are written @tags/<CODE>, so a library tagged outside the platform can be imported and then published together.

Defaults copied onto a user sequence​

defaultPersistent, defaultRevisable, defaultClosable, defaultDismissable, defaultUnscheduledSubmission, defaultSchedule and defaultSurfaceId are copied onto a user sequence when it is made, for whatever the assignment didn't set. They are not a live link: changing one reaches user sequences made afterwards, and anything already assigned keeps what it was given. When one participant's item behaves unexpectedly, read their user sequence before the sequence.

Who can start it, and what Progress shows​

  • explore: hidden (the default): only staff or a journey can assign it. shown: it shows in the participant's Explore and they can start it themselves; otherwise a self-start is refused with sequence_not_self_enrollable.
  • progress decides whether, and where, its responses have a row on the participant's Progress tab. shown is the default: a row among the responses. featured puts the row at the top of Progress, above health data, for the one or few sequences a programme is about; it shows once, never again among the responses. Set hidden on anything that only makes the programme work, such as consent. Changing it reaches everyone it is already assigned to.

Scores and bands​

A sequence's scores turn a submission into named numbers, each with an optional band. Journeys branch on them and Progress draws them.

  • Scores are worked out top to bottom; a score reads atoms on the sequence's pages and any score above it. With no atoms named, it reads every atom that can contribute.
  • What contributes: a number or slider (held to its min/max); the chosen option's points on single_select; the sum of the ticked options' points on multi_select; the chosen option's points on boolean, or 1 and 0 when none are written. Nothing else contributes, and only atoms the participant was shown count.
  • An option with no points drops out, rather than counting as zero. Under sum that reads the same; under average it also leaves the divisor and doesn't count towards minRespondedSources. Give the zero option 0.
  • strategy combines the sources (sum, average, max, min); then scale (multiply, then add) converts to the instrument's published scale, and the band is the one with the highest min at or below the result.
  • Below minRespondedSources there is no score and no band, never a zero. Give any journey branch that reads a score a way through for when none arrives.
  • Bands run from their min to the next band's, the last with no upper limit; a score below the first has no band. Publishing refuses bands out of order or a repeated name.
  • The server scores every response against the version the response records, and its scores are the ones kept; the phone works the same out at once so Progress and the next journey node don't wait. A change to the scores never rescores responses already on file.
  • A score a journey reads is load-bearing: publishing a version that removes a score code or a band name that a journey in use reads is refused, naming the journeys.

highlightDisplayValue says what the sequence's row on Progress leads with: a score, a band, the first response, that it was completed, or nothing.

Retiring a sequence​

Archive it. An archived sequence still resolves for everyone it is assigned to and can't be assigned again. Deleting one a journey references is refused with sequence_in_use.