chore(docs): update Therapy and Monitoring Manager documentation (#1774)

* chore(docs): update Therapy and Monitoring Manager documentation

* chore(docs): update Therapy and Monitoring Manager documentation

* chore(docs): update Therapy and Monitoring Manager documentation

* chore(docs): update Therapy and Monitoring Manager documentation

* chore(docs): update Therapy and Monitoring Manager documentation

* chore(docs): update Therapy and Monitoring Manager documentation

* chore(docs): update Therapy and Monitoring Manager documentation

* chore(docs): update Therapy and Monitoring Manager documentation

* chore(docs): update Therapy and Monitoring Manager documentation

* chore(docs): update Therapy and Monitoring Manager documentation

* chore(docs): update Therapy and Monitoring Manager documentation

* chore(docs): update Therapy and Monitoring Manager documentation

* chore(docs): update Therapy and Monitoring Manager documentation

* chore(docs): update Therapy and Monitoring Manager documentation

* chore(docs): update Therapy and Monitoring Manager documentation

* chore(docs): update Therapy and Monitoring Manager documentation

* chore(docs): update Therapy and Monitoring Manager documentation

* chore(docs): update Therapy and Monitoring Manager documentation

* chore(docs): update Therapy and Monitoring Manager documentation

* chore(docs): update Therapy and Monitoring Manager documentation

* chore(docs): update Therapy and Monitoring Manager documentation

* chore(docs): update Therapy and Monitoring Manager documentation

* chore(docs): update Therapy and Monitoring Manager documentation

Author: bot-targa

docs/runtime_suite/therapy-and-monitoring-manager/10_overview.md

@@ -177,7 +177,7 @@ For each prototype you need to define:
 - the name;
 - the schema;
 - the labels for the schema fields (**required** only if you use the TMM with the companion FE component);
-- the values for the schema fields (**required** only if you use the TMM with the companion FE component);
+- the values for the schema fields;
 - the hints for the schema fields (only for therapy directives, should provide a list of admitted or suggested values for a schema field).
 
 TMM supports localization for `name`, `labels` and `hints`, using a syntax like the following (`en` is ISO 639-1 language code for English, `it` for Italian):
@@ -423,48 +423,86 @@ The integrated validation system currently supports the following threshold vali
 }
 ```
 
-:::warning
+:::danger
+
+The integrated validation system is designed under two assumptions.
+
+- The property of the detection referred by a threshold contains one or two numeric values; if the value is not a number or an array of two numbers, depending on the operator, an error is returned.
+- The `propertyName` is treated as the path of the field in the detection containing the value to compare against the threshold, unless a different path is specified under prototype `values`; see the next section for more information.
+
+:::
+
+Additional information about the API requirements and the setup of the external validation service are available in the [*Configuration* section][thresholds-validation].
+
+### Threshold evaluation
+
+When a detection is submitted, its value is checked against each threshold defined in the associated monitoring plan.
 
-The value of the `propertyName` should be the path to the value of the specific attributes in the prototype schema. If your schema is not a plan object you can use the `values` on the prototype to specify the path.
-Here you can find the examples:
+In this context, the threshold `propertyName` is treated as the path of the field in the detection `value` object containing the numeric value to be validated.
+
+So, given a threshold looking like this:
+
+```json
+{
+  "propertyName": "systolicBloodPresure",
+  "thresholdOperator": "gt",
+  "thresholdValue": 130
+}
+```
+
+and a detection looking like this:
 
-- If you have a plane object the `propertyName` will be simply equal to that record like `systolicBloodPresure`  or `diastolicBloodPresure`.
 ```json
 {
   "systolicBloodPresure": 120,
-  "diastolicBloodPresure": 66
+  "diastolicBloodPresure": 75
 }
 ```
 
-- If you have a a complicated schema the `propertyName` should be equal to that path of the value like `observations[0].value` for `systolicBloodPresure` and `observations[1].value`  for  the value of `diastolicBloodPresure`.
+the TMM can assert that the `systolicBloodPresure` has a safe value, since `120` is lower than `130`.
+
+If your schema is not a plain object, but for example has array and/or nested fields, we recommend using the `values` field on the prototype to map the `propertyName` to the actual `path` and make the prototype configuration more human readable.
+
+So, given the same threshold as before and a detection looking like this:
+
 ```json
 {
   "period": {
-    "startDate": "2024-01-01"
+    "start": "2024-01-07T19:10:00Z",
   },
   "observations": [
     {
-      "code": "systolicBloodPresure",
+      "name": "Diastolic blood pressure",
       "unit": "mmHg",
-      "value": 120
+      "value": 75
     },
     {
-      "code": "diastolicBloodPresure",
+      "name": "Systolic blood pressure",
       "unit": "mmHg",
-      "value": 66
+      "value": 120
     }
   ]
 }
 ```
-:::
 
-:::danger
+you can add the following `values` to the prototype:
 
-The integrated validation system is designed under the assumption that the property of the detection value referred by a threshold contains one or two numeric values. If the value is not a number or an array of two numbers, depending on the operator, an error is returned.
+```json
+{
+  "values": {
+    "diastolicBloodPresure": { 
+      "path": "observations[0].value"
+    },
+    "systolicBloodPresure": { 
+      "path": "observations[1].value"
+    }
+  }
+}
+```
 
-:::
+which is basically a way to tell the TMM that the values of the `diastolicBloodPresure` and `systolicBloodPresure` properties can be found in the `value` field of the first and second object inside the `observations` array field, respectively.
 
-Additional information about the API requirements and the setup of the external validation service are available in the [*Configuration* section][thresholds-validation].
+When the TMM needs to compare a detection against a thresholds, it first performs a lookup on the prototype `values` based on the threshold `propertyName`: if there is a match, like in our example for `systolicBloodPresure`, the TMM gets the value from the detection at the path specified in the `path` field of the prototype value (in our case `observations[1].value`).
 
 ## Notifications
 

docs/runtime_suite/therapy-and-monitoring-manager/20_configuration.md

@@ -182,7 +182,7 @@ Note that, modifying an identifier in an already running system can lead to inco
 
 * **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.
+* **Values**: the values for the schema fields, each one must be an object containing the path of the field in the detections containing the 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. 
 
@@ -348,12 +348,12 @@ By default, the TMM does not validate detections against the thresholds. If you
 
 - set the TMM **VALIDATION_SERVICE** [environment variable][environment-variables] 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][external-validation-service-api];
+  - deploy a custom microservice exposing a HTTP API following the specifications provided in the [section below][external-validation];
   - set the TMM **VALIDATION_SERVICE_URL** [environment variable][environment-variables] to the HTTP(s) address of your service (both public and internal cluster URLs will work).
 
-### External Validation Service API
+### External validation
 
-The External Validation Service must expose the following endpoints:
+The External validation relies on a service exposing an HTTP interface with the the following endpoints:
 
 - `POST /validations/` to validate a detection against the monitoring thresholds.
 
@@ -405,6 +405,6 @@ The TMM currently generates the following events you can refer in the configurat
 [crud-detections]: #detections "Detections | CRUD collections | Configuration"
 [crud-monitorings]: #monitorings "Monitorings | CRUD collections | Configuration"
 [environment-variables]: #environment-variables "Environment variables | Configuration"
-[external-validation-service-api]: #external-validation-service-api "External Validation Service API | Thresholds validation | Configuration"
+[external-validation]: #external-validation "External validation | Thresholds validation | Configuration"
 
 [errors]: ./30_usage.md#errors

docs/runtime_suite/therapy-and-monitoring-manager/30_usage.md

@@ -58,7 +58,7 @@ The therapy data model add the concept of `directives`, which is an object follo
 
 The monitoring data model add the concept of `notes` and `thresholds`. The notes field contains the physician prescriptions, while a threshold is an object with the following properties:
 
-* `propertyName`: name of the property on which the threshold is evaluated;
+* `propertyName`: name of the property on which the threshold is evaluated; it should correspond to the path of the detection field containing the value to compare against the threshold, if your detection have nested or array fields you should specify the mapping between the `propertyName` and its path under the prototype `values` field (more details in the [Overview section][threshold-evaluation]);
 * `thresholdOperator`: operator to use in the threshold evaluation. Available options are: `gt`, `lt`, `gte`, `lte`, `eq`, `between`, `notBetween`;
 * `thresholdValue`: the value with which to evaluate the threshold (a single number for `gt`, `lt`, `gte`, `lte` and `eq` operators, an array of two numbers indicating a range for the `between` and `notBetween` operators).
 
@@ -946,6 +946,7 @@ The computation is performed for each plan according to the following algorithm,
 
 [overview]: ./10_overview.md "Overview page"
 [adherence-compliance]: ./10_overview.md#adherence-and-compliance "Adherence and compliance | Overview"
+[threshold-evaluation]: ./10_overview.md#threshold-evaluation
 
 [configuration]: ./20_configuration.md "Configuration page"
 [environment-variables]: ./20_configuration.md#environment-variables "Environment variables | Configuration"

docs/runtime_suite/therapy-and-monitoring-manager/40_migration.md

@@ -12,6 +12,12 @@ Instead, modify the source file and run the aggregator to regenerate this file.
 
 This document provides information to migrate from a previous version of the service.
 
+## 0.5.1
+
+No change required from previous version.
+
+If you use the [`ck-threshold-modal` Care Kit component][care-kit-ck-threshold-modal] and any of your prototypes includes the `values` field, please note that this version of the TMM is not compatible with Care Kit v2.9.0.
+
 ## 0.5.0
 
 ### CRUD collections
@@ -42,3 +48,5 @@ Add the following fields to the [detections CRUD collection][crud-detections]:
 
 [crud-detections]: ./20_configuration.md#detections
 [crud-monitorings]: 20_configuration.md#monitorings
+
+[care-kit-ck-threshold-modal]: /runtime_suite/care-kit/20_components/50_ck-threshold-modal.md

docs/runtime_suite/therapy-and-monitoring-manager/changelog.md

@@ -15,6 +15,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.1] 2024-11-12
+
+### Fixed
+
+- Convert thresholds `propertyName` according to prototype `values` when creating or updating a monitoring plan
+
 ## [0.5.0] 2024-10-30
 
 ### Changed