uask-dom v1.2.0

U-ASK Domain Model

U-ASK domain model classes and builders. This library implement an internal domain specific language as described in Martin Fowler's Domain Specific Languages.

This library is intended to be used with U-ASK Management System and U-ASK Web Application.

• Install
• Survey
• Rules
• Workflows
• Participant
• Mutations
• DSL reference

Note: npm scripts needs bash ; please configure git bash as script shell for npm on Windows.

Install

npm Install uask-dom

Usage

Survey construction

A Survey is composed of Page objects. Page objects are hierarchical, they include other Page objects or PageItems leaf objects.

Page objects are grouped in PageSet objects that represent questionnaires. A Survey may have multiple questionnaires.

PageItem represent a question, they have a wording and a type. They may be involved in Rule objects that control the value of question answers.

Survey objects are complex graphes, construction is easier with fluent builders :

import { builder } from "uask-dom"

const b = builder();

b.survey("First-Survey")
  .pageSet("Questionnaire").pages("Questions");

b.page("Questions")
  .question("Ok?", "OK", b.types.yesno)
  .question("When:", "WHEN", b.types.date());

const survey = b.build();

The result is a Survey object with PageSet, Page and PageItem objects that reflects the stucture of the fluent program above.

The complete refercence for survey buiders is below

Rules

A PageItem may be the target or a Rule. For example a page item can enforce that a value must be provided.

b.page("Questions")
  .question("Ok?", "OK", b.types.yesno)
  .required()
  // ...

A PageItem value can have a default value :

b.page("Questions")
  // ...
  .question("When:", "WHEN", b.types.date())
  .defaultValue("@TODAY");

Rules are executed in order of appearance of their target PageItem in the DSL ; for a given target they are executed in order of deacreasing precedence.

note: parameters followed by a * may be replaced by a formula, a formula is constructed wih the computed keyword:

b.page("Questions")
  // ...
  .question("When:", "WHEN", b.types.date())
  .inRange("2022-01-01", b.computed("@TODAY"));

A critical rule fires an event that will be notified to users which workflow subscribed to that event (see Derived workflows).

b.page("Questions")
  // ...
  .question("When:", "WHEN", b.types.date())
  .critical("before_2022", "before 2022", b.computed("WHEN < #2022-01-01#"));

Workflows

A Survey has one or more Workflow objects. A workflow represents the page sets a user has access to and when he can create an interview related to a given page set.

Main workflow

In the main workflow a page set may :

• appear once or multiple times
• belong to the sequence or be auxiliary

• terminate the workflow (or not)

The workflow sequence follows the following stucture:

The fisrt interview of a participant always refercences the starting page set. Subsequent interviews will reference pages sets in order defined in the sequence. Initial page sets appears in only one interview and follow up page sets can be repeated in multiple interviews, always following the sequence.

Terminal page sets terminate the workflow: no more interview could be created for the participant.

Auxiliary page sets can appear any time after the sequence started.

Workflow creation is part of Survey construction:

import { builder } from "uask-dom"

const b = builder();

b.survey("First-Survey")
  .pageSet("Initial 1").pages("I1")
  .pageSet("Initial 2").pages("I2")
  .pageSet("Follow up 1").pages("F1")
  .pageSet("Follow up 2").pages("F2")
  .pageSet("Terminal 1").pages("T1")
  .pageSet("Terminal 2").pages("T1")
  .pageSet("Auxiliary 1").pages("A1")
  .pageSet("Auxiliary 2").pages("A2")

//...

b.workflow()
  .initial("Initial 1", "Initial 2")
  .followUp("Follow up 1", "Follow up 2")
  .terminal("Terminal 1", "Terminal 2")
  .auxiliary("Auxiliary 1", "Auxiliary 2")

const survey = b.build();

Derived workflows

Derived workflows are built from the main workflow, giving access to a restricted subset of the page sets. They have the same sequence, terminal and auxiliary page sets.

Derived workflows can optionally have associated notifications. Notifications refers to critical events declared with a question. Users with that workflow will receive notifications when the event fires.

A derived workflow is identified by its name (which can not be "main"), and optionally a specifier. Names are not restricted in this library but in U-ASK Management System the allowed values are :

• writer
• reader
• administrator
• superadministrator
• developer The specifier if any, is positionned after the name, separated with : (e.g. "writer:investigator", "reader:coordinator").

// ...

b.workflow("writer:investigator")
  .withPageSets("Follow up 1", "Follow up 2")
  .notify("special")

Participant construction

A Participant participes to a Survey ; it belongs to a Sample.

Participant contains Interview objects that reference a PageSet and contains InterviewItem objects.

InterviewItem holds a value and represent an answer to a PageItem (a question).

Participant may also be build using fluent buiders.

The following code builds a Participant with code "11A" in the given sample of the given survey. The participant will have one interview, corresponding to page set "Questionnaire" with two answers, for items corresponding to variables "OK" and "WHEN".

import { ParticipantBuilder } from "uask-dom";

const builder = new ParticipantBuilder(survey, "11A", sample);
builder.interview("Questionnaire")
  .item("OK").value(false)
  .item("WHEN").value(new Date());
const participant = builder.build();

the same can be done using domain model objects instead of string identifiers:

import { ParticipantBuilder } from "uask-dom";

const questionnaire: PageSet = //...
const Ok: PageItem = //...
const When: PageItem = //...

const builder = new ParticipantBuilder(survey, "11A", sample);
builder.interview(questionnaire)
  .item(Ok).value(false)
  .item(When).value(new Date())
const participant = builder.build();

See ./src/example/index.ts for an example of fluent builders usage.

Domain model objects mutations

Domain model objects are mostly immutable. When a domain model object needs an update in some business logic, a new version of the object is produced :

const pageItem = new PageItem("Are you OK ?", "OK", QuestionTypes.yesno);
const interviewItem = new InterviewItem(pageItem, true);
//...
const updatedInterviewItem = interviewItem.update({ value: false });

Domain object collections are also immutable, if a new version of an object has been produced, a new collection including the new object must be created :

const interviewItems = DomainCollection(interviewItem, ...);
//...
const updatedInterviewItems = interviewItems.update(
  a => a == interviewItem ? updatedInterviewItem : a
);

Mutations on Patient, Interview and InterviewItem can be achieved using the corresponding builders. The following snippet will created and updated version the participant, with items corresponding to variables "OK" and "WHEN" updated in interview corresponding do page set Questionnaire and identified by the nonce 11145786.

import { ParticipantBuilder } from "uask-dom";

const participant: Patient = //...

const builder = new ParticipantBuilder(survey, participant)
builder.interview("Questionnaire", 11145786)
  .item("OK").value(false)
  .item("WHEN").value(new Date())
const updatedPatient = builder.build();

The same can be done with domain models instead of string identifiers :

import { ParticipantBuilder } from "uask-dom";

const participant: Patient = //...
const questionnaire11145786: Interview = //...
const Ok: PageItem = //...
const When: PageItem = //...

const builder = new ParticipantBuilder(survey, participant)
builder.interview(questionnaire11145786)
  .item(Ok).value(false)
  .item(When).value(new Date())
const updatedPatient = builder.build();

DSL reference

Survey and visit construction

Survey options

Example

b.survey('Demo-eCRF')
  .defaultLang('fr')
  .visit('INCL')
    .translate('fr', 'Inclusion')
    .translate('en', 'Inclusion')
    .dateVariable('DATE_VIS')
    .pages(b.mandatory('PATIENT_INFO'), 'ANTECED')

Page and question construction

Variable types

The third argument of .question(wording, variable, type) is the result of one of

Example

b.page('INCL')
  .translate('fr', 'Inclusion')
  .translate('en', 'English')
  .question('Date de la visite', 'DATE_VIS', b.types.date())
    .translate('en', 'Visit date')
    .required()
    .inRange('#2000-01-01#', b.computed('@TODAY'))
  .question('Sexe', 'SEX',
    b.types.choice('one', 'H', 'F', 'ND')
      .wording('Homme', 'Femme', 'Non déterminé')
      .translate('en', 'Male', 'Female', 'Undetermined'))
    )
    .translate('en', 'Sex')

Computed formulas

A formula are composed of :

• operators

  operator
  + - * /	arithmetic operators
  < > <= >= == !=	comparison operators
  ? ... : ...	ternary operator
  && || == !=	logical operators
  (...)	sub expressions

• values

  value
  0, 1, 2 ...	numbers (may be decimals)
  '...'or "..."	texts
  #YYYY-MM-DD#	dates

• variables

  variable
  X, Y, Z ...	current value of a variable declared in the questions
  $X, $Y, $Z ...	previous value of a variable declared in the questions
  @LASTIN	last input date for the participant
  @UNDEF	undefined value
  @ACK	acknowledged or true value
  @THISYEAR	current year
  @TODAY	current date

• functions

  function
  ~IN(VAR, value)	returns @ACK if given variable of type .choice('many') contains the given value

Examples

b.page('...')
 .question('Où souffrez-vous ?', 'LOC', b.types.choice('many', 'MAIN', 'DOS', 'JAMBE', 'TÊTE', 'AUTRE')
 .question('Si AUTRE, précisez', 'LOC_AUTRE', b.types.text)
   .activatedWhen(~IN('LOC, "Autre")')

b.page('...')
  question('Date de la visite', 'DATE_VIS', b.types.date())
 .question('Confirmez que la date est postérieure à ce jour', '__DATE_POST', b.types.acknowledge)
   .required()
   .visibleWhen('DATE_VIS>@TODAY')

Question layouts

Questions that are related may be viewed as tables or recordsets

A table represents variables that can be arranged as

	column A	colmumn B
row1	A1	B1
row2	A2	B2

A recordset represents variables that can have multiple instances in the same form

column A	colmumn B
A(1)	B(1)
A(2)	B(2)
...	...

This is achieved by using DSL syntax in the question wordings :

Examples

b.page('...')
  .question('Red cells -> Result', 'RES_BLOOD', b.types.real)
  .question('Red cells -> Interpretation', 'INT_BLOOD', b.choice('one', 'normal', 'abnormal'))
  .question('Haemoglobin -> Result', 'RES_BLOOD', b.types.real)
  .question('Haemoglobin -> Interpretation', 'INT_HAEMO', b.choice('one', 'normal', 'abnormal'))

	Résult	Interpretation
Red cells	RES_BLOOD	INT_BLOOD
Haemoglobin	RES_BLOOD	INT_HAEMO

b.page('...')
  .question('-> Year', 'YEAR', b.types.integer)
  .question('-> Treatment', 'TREAT', b.types.text)
  .question('-> Dosage', 'DOS', b.types.text)

YEAR	Treatment	Dosage
YEAR(1)	TREAT(1)	DOS(1)
YEAR(2)	TREAT(2)	DOS(2)
...	...	...

Informationnal classes and directives

The question comments can be used to add information to a question. Directives gives richer wording capabilities and classes are question categories indications. Comment can be written as : directives...{classes...}. Classes begins with a dot .

Example

b.page(' ')
 .question('Pain scale', 'PAIN', b.types.scale(1, 10))
 .comment('<No pain | Maximum pain>{.row}')

Pain scale   No pain   1   2   3   4   5   6   7   8   9   10   Maximum pain