Version: 13.x (Current)

Configuration

The Therapy and Monitoring Manager can be configured to fit the specific scenarios in which it has to be used.

Environment variables

Name	Required	Default	Description
HTTP_PORT	No	3000	The port exposed by the service.
LOG_LEVEL	No	`info`	The level of the log: `trace`, `debug`, `info`, `warn`, `error`, `fatal`.
PROTOTYPES_CONFIG_FILE_PATH	No	-	Path of the config map file containing the prototypes.
PROTOTYPES_SERVICE_URL	No	-	URL of an HTTP service returning an array of prototypes.
CRUD_SERVICE_URL	No	http://crud-service	HTTP(S) URL of the CRUD service.
MONITORINGS_CRUD_NAME	No	monitorings	Name of the CRUD collection containing the monitorings.
THERAPIES_CRUD_NAME	No	therapies	Name of the CRUD collection containing the therapies.
DETECTIONS_CRUD_NAME	No	detections	Name of the CRUD collection containing the detections.
DETECTIONS_GRACE_PERIOD	No	30	Number of days after the end of a therapy or monitoring during which adherence and compliance are still updated (in case the patient submit detections late)
DETECTIONS_TIME_ZONE	No	UTC	Default detections time zone. Must be a valid IANA time zone.
CRON_SCHEDULE	No	`0 0 * * *`	Cron schedule for the computation of the adherence and compliance metrics in the `DETECTIONS_TIME_ZONE` time zone.
VALIDATION_SERVICE	No	integrated	If TMM should use the integrated or an external validation service to check thresholds (admitted values: `integrated`, `external`).
VALIDATION_SERVICE_URL	No	-	HTTP(S) URL of the external validation service. If `VALIDATION_SERVICE` is `external`.
DEFAULT_ADHERENCE_STATUS	Yes	-	Default value for adherenceStatus
DEFAULT_ADHERENCE_TOLERANCE_FREQUENCY	Yes	-	Default value for adherenceToleranceFrequency
DEFAULT_ADHERENCE_TOLERANCE_TIME	Yes	-	Default value for adherenceToleranceTime
DEFAULT_ADHERENCE_MINIMUM_PERCENTAGE	Yes	-	Default value for adherenceMinimumPercentage
DEFAULT_COMPLIANCE_STATUS	Yes	-	Default value for adherenceStatus
DEFAULT_COMPLIANCE_MINIMUM_PERCENTAGE	Yes	-	Default value for complianceMinimumPercentage
MAX_PATIENT_ACTIVE_PLANS	No	-	Maximum number of active therapies or monitorings associated to the same prototype for each patient.
NOTIFICATION_MANAGER_URL	No	-	HTTP(S) URL of the notification manager.

Prototypes definition

As described in the overview section, the prototypes are essentially JSON Schemas to apply to the monitoring detections entered by a patient or therapy directives entered by the physician in order to validate the corresponding values.

The service will load the prototypes from the following locations (in the given order):

a config map specified in the PROTOTYPES_CONFIG_FILE_PATH environment variable and containing an array of prototypes in JSON format;
an HTTP service specified in the PROTOTYPES_SERVICE_URL environment variable, returning a JSON response containing an array of prototypes.

If one or more prototypes have the same identifier, a PROTOTYPES_DUPLICATED error is raised and the service fails to start.

A prototype example can be used to validate detections related to blood pressure. In this case a typical detection is an object composed by two integer values, the minimum and the maximum blood pressure, which must be within a certain range. For instance, entering a maximum blood pressure to 600 is not acceptable. The corresponding prototype would define a JSON Schema validating the fact that the detection value is an object composed by two integer values which must be within specific ranges to be considered valid.

{
  "identifier": "bloodPressure",
  "type": "measurement",
  "name": {
    "en": "Blood Pressure",
    "it": "Pressione sanguigna"
  },
  "schema": {
    "type": "object",
    "properties": {
      "minimumBloodPressure": {
        "type": "integer",
        "minimum": 60,
        "maximum": 150
      },
      "maximumBloodPressure": {
        "type": "integer",
        "minimum": 80,
        "maximum": 250
      }
    },
    "required": [
      "minimumBloodPressure",
      "maximumBloodPressure"
    ]
  },
  "labels": {
    "minimumBloodPressure": {
      "en": "Minimum pressure",
      "it": "Pressione minima"
    },
    "maximumBloodPressure": {
      "en": "Maximum pressure",
      "it": "Pressione massima"
    }
  },
  "values": {
    "minimumBloodPressure": { 
      "path": "observations[0].value"
    },
    "maximumBloodPressure": { 
      "path": "observations[1].value"
    }
  },
}

A prototype can be used also to provide custom fields the physician can fill to provide specific directives. In the following example, the prototype defines three directive fields: nutritionalAdvices, personalAdvices and diet, all available with English and Italian localization and diet having a list of suggested values, that can be rendered on the therapy form field as options of a select field.

{
  "identifier": "nutritionalTherapy",
  "type": "therapy",
  "name": {
    "en": "Nutritional Therapy",
    "it": "Terapia Nutrizionale"
  },
  "schema": {
    "type": "object",
    "properties": {
      "nutritionalAdvices": {
        "type": "string"
      },
      "personalAdvices": {
        "type": "string"
      },
      "diet": {
        "type": "string"
      }
    }
  },
  "labels": {
    "nutritionalAdvices": {
      "en": "Advices for a healthy and correct diet",
      "it": "Consigli di una sana e corretta alimentazione"
    },
    "personalAdvices": {
      "en": "Personal recommendations",
      "it": "Consigli personalizzati"
    },
    "diet": {
      "en": "Diet",
      "it": "Dieta"
    }
  },
  "hints": {
    "diet": [
      {
        "en": "Low calorie 1200 KCAL (BEE ≤ 1300KCAL)",
        "it": "Ipocalorica 1200 KCAL (BEE ≤ 1300KCAL)"
      },
      {
        "en": "Low calorie 1400 KCAL (BEE [1400-1600] KCAL)",
        "it": "Ipocalorica 1400 KCAL (BEE [1400-1600] KCAL)"
      },
      {
        "en": "Low calorie 1600 KCAL (BEE [1600-1800] KCAL)",
        "it": "Ipocalorica 1600 KCAL (BEE [1600-1800] KCAL)"
      },
      {
        "en": "Low calorie 1800 KCAL (BEE [1800-2000] KCAL)",
        "it": "Ipocalorica 1800 KCAL (BEE [1800-2000] KCAL)"
      }
    ]
  }
}

Prototype data model

The prototype is a JSON object composed by the following properties.

Identifier: the prototype identifier. This identifier is assigned by the prototype creator, it is not the identifier given by the system and it is used to link the therapy and the monitoring objects.

danger

Note that, modifying an identifier in an already running system can lead to inconsistencies during detection checks. The identifier should be immutable. If it has to be updated, please be sure that is not already used as reference in the therapies and monitorings objects.

Type: the prototypes type. There are two options:
- measurement refers to monitoring detections, in which a patient has to insert a measurement representing its current situation;
- therapy refers to therapy directives, in which a physician has to insert specific therapy details.
Name: the prototype name, as a string or translation object. It has no identification purpose and it is used to better identify the prototype objective.
Schema: the property containing the schema used to validate the detection value or therapy directives. The schema must follow JSON Schema 7.
Labels: the labels for the schema fields, each one can be a string or translation object.
values: the values for the schema fields, each one must be an object containing the path of the field in the detection value containing the corresponding value to compare against the thresholds.
Hints: the hints for the schema fields, each one can be a string or translation object. This is only supported by therapy directives, to provide a list of admitted or suggested values for the field.

CRUD collections

In order to make the TMM works properly, a set of collections must be configured. These collections must be created by the user of the TMM.

note

You can use the following JSON files in the MongoDB CRUD section of the console to import the list of fields when creating the CRUD collections:

Therapies

Name	Type	Required (Yes/No)	Nullable (Yes/No)
planName	`string`	Yes	No
prototypeId	`string`	Yes	No
directives	`Object`	No	No
startDate	`Date`	Yes	No
endDate	`Date`	No	No
each	`Array of string`	No	No
times	`number`	No	No
hours	`Array of string`	No	No
doctorId	`string`	Yes	No
patientId	`string`	Yes	No
adherenceStatus	`string`	Yes	No
adherenceToleranceTime	`number`	No	No
adherenceToleranceFrequency	`string`	No	No
adherenceMinimumPercentage	`number`	No	No
complianceStatus	`string`	Yes	No
complianceMinimumPercentage	`number`	No	No
isPatientAdherent	`boolean`	No	No
isPatientAdherentLastUpdatedAt	`Date`	No	No
isPatientCompliant	`boolean`	No	No
isPatientCompliantLastUpdatedAt	`Date`	No	No

The directives field will have the fields specified in the prototype schema, depending on the therapy prototypeId.

Monitorings

Name	Type	Required (Yes/No)	Nullable (Yes/No)
planName	`string`	Yes	No
prototypeId	`string`	Yes	No
notes	`string`	No	No
startDate	`Date`	Yes	No
endDate	`Date`	No	No
each	`Array of string`	No	No
times	`number`	No	No
hours	`Array of string`	No	No
doctorId	`string`	Yes	No
patientId	`string`	Yes	No
adherenceStatus	`string`	Yes	No
adherenceToleranceTime	`number`	No	No
adherenceToleranceFrequency	`string`	No	No
adherenceMinimumPercentage	`number`	No	No
complianceStatus	`string`	Yes	No
complianceMinimumPercentage	`number`	No	No
isPatientAdherent	`boolean`	No	No
isPatientAdherentLastUpdatedAt	`Date`	No	No
isPatientCompliant	`boolean`	No	No
isPatientCompliantLastUpdatedAt	`Date`	No	No
thresholds	`Array of object`	No	No
assignedDevices	`Array of string`	No	No

For the field thresholds you should add the following JSON Schema to the CRUD configuration:

{
  "properties": {
    "propertyName": {
      "type": "string",
      "description": "Name of the property of the detection value the threshold is evaluated on"
    },
    "thresholdOperator": {
      "type": "string",
      "description": "Name of the operator",
      "enum": [
        "gt",
        "lt",
        "gte",
        "lte",
        "eq",
        "between",
        "notBetween"
      ]
    },
    "thresholdValue": {
      "oneOf": [
        {
          "type": "number",
          "description": "Threshold value"
        },
        {
          "type": "array",
          "items": { "type": "number" },
          "minItems": 2,
          "maxItems": 2,
          "description": "Threshold range"
        }
      ]
    }
  },
  "required": [
    "propertyName",
    "thresholdOperator",
    "thresholdValue"
  ]
}

tip

You can configure at most one threshold for each detection property, using the between and notBetween operators when applicable instead of defining multiple thresholds based on the gt, gte lt and lte operators.

If the detection value has nested or array fields you can use a dot or bracket notation respectively in the propertyName to refer a nested field or an element inside an array.

For example, if the value is an object looking like this:

{ "a": [{ "b": { "c": 3 } }] }

then you could use any of the following notations in the propertyName field:

a[0] to refer to the first element of the array, that is { "b": { "c": 3 } };
a[0].b to refer to the value of the b field, that is { "c": 3 };
a[0].b.c to refer to the value of the nested c field, that is 3.

If you are using the integrated validation service, remember that the propertyName field must refer a numeric field of the detection value.

Detections

danger

If you use the integrated validation service, field names in the value object should only contain alphanumeric characters or underscores due to implementation details. If you use an external service, instead, the TMM has no such limitation.

Name	Type	Required (Yes/No)	Nullable (Yes/No)
planType	`String`	Yes	No
planId	`String`	Yes	No
value	`Object`	No	No
observedAt	`Date`	Yes	No
doctorId	`String`	No	No
patientId	`String`	Yes	No
isCompliant	`Boolean`	No	No
deviceId	`String`	No	No
thresholds	`Array of object`	No	No
thresholdsExceeded	`Boolean`	No	No

Thresholds validation

By default, the TMM does not validate detections against the thresholds. If you want to use the integrated validation or an external service to run custom validations, you need to perform the following steps:

set the TMM VALIDATION_SERVICE environment variable to internal or external;
if you are using an external service:
- deploy a custom microservice exposing a HTTP API following the specifications provided in the section below;
- set the TMM VALIDATION_SERVICE_URL environment variable to the HTTP(s) address of your service (both public and internal cluster URLs will work).

External Validation Service API

The External Validation Service must expose the following endpoints:

POST /validations/ to validate a detection against the monitoring thresholds.

`POST /validations/`

The endpoint must accept in the body a JSON object with the following properties:

detection: the detection to validate, an object itself with the same fields available in the detections CRUD collection;
thresholds: an array of the monitoring thresholds, each one being an object with the same schema of the thresholds field of the monitorings CRUD collection.

If the validation is performed without errors, the endpoint must return 200 as status code and a body containing a JSON array, each element representing the result of the validation for a corresponding threshold received in the request (thresholds) and the following properties:

threshold (object, required): the monitoring threshold (with the same fields as in the request);
value (any, required): the value the threshold is evaluated on;
status (string, required): a string indicating if the detection exceeded (KO) or not (OK) the threshold;
error (string): if status is KO, this field must contain an arbitrary string indicating the error type (for example Threshold Exceeded);
message (string): if status is KO, this field must contain a human-readable string indicating the error message, useful when sending the notification to the physician (for example, 'minimumBloodPressure' must be lower than 120, but was 140).

If an error occurs during the validation process, the endpoint should return the appropriate 4xx or 5xx status code.

info

The TMM forwards the response of the validation service to the Notification Manager service in order to notify the physician if the detection exceeded one or more thresholds. Therefore, in the template of the notification message you can refer any information available in the response of the external validation service. The integrated validation service produces an identical response, so the template will work exactly the same, no matter which service you use.

Notifications

danger

This section describes the integration with a future version of the Notification Manager service, which is currently under development. The information may not reflect the final specifications of the service and may be subject to breaking changes.

To send notifications to patients and physicians you need to set the NOTIFICATION_MANAGER_URL environment variable and configure the events, channels, recipients, ... directly in the Notification Manager service (see the component documentation for more details).

The TMM currently generates the following events you can refer in the configuration of the Notification Manager service:

TMM/ThresholdExceeded/v1 is the event generated when a detection exceeds one or more monitoring thresholds.

Environment variables​

Prototypes definition​

Prototype data model​

CRUD collections​

Therapies​

Monitorings​

Detections​

Thresholds validation​

External Validation Service API​

POST /validations/​

Notifications​

Environment variables

Prototypes definition

Prototype data model

CRUD collections

Therapies

Monitorings

Detections

Thresholds validation

External Validation Service API

`POST /validations/`

Notifications