From 25eecebca0a4bd745b1c9132a0692734b75467a5 Mon Sep 17 00:00:00 2001 From: lostlevels Date: Tue, 26 Aug 2025 15:43:31 -0700 Subject: [PATCH 1/6] [BACK-3970] Add spec for configurable TIDE report categories. --- reference/clinic.v1.yaml | 57 +++++++++++++++++++ .../clinic/models/tide/tideCategory.v1.yaml | 0 .../clinic/models/tide/tideConfig.v1.yaml | 2 +- .../clinic/models/tide/tideFilters.v1.yaml | 8 +-- .../clinic/models/tide/tideSettings.v1.yaml | 0 .../clinic/models/tide/tideThresholds.v1.yaml | 25 ++++++++ 6 files changed, 84 insertions(+), 8 deletions(-) create mode 100644 reference/clinic/models/tide/tideCategory.v1.yaml create mode 100644 reference/clinic/models/tide/tideSettings.v1.yaml create mode 100644 reference/clinic/models/tide/tideThresholds.v1.yaml diff --git a/reference/clinic.v1.yaml b/reference/clinic.v1.yaml index 26d707f4..7a5460e8 100644 --- a/reference/clinic.v1.yaml +++ b/reference/clinic.v1.yaml @@ -269,6 +269,15 @@ paths: in: query name: lastDataCutoff description: Inclusive + - schema: + type: array + items: + type: string + in: query + name: categories + description: Comma-separated list of category names to include in the report. Omit to include all. + style: form + explode: false '/v1/clinics/{clinicId}/patients': parameters: - $ref: '#/components/parameters/clinicId' @@ -1812,6 +1821,44 @@ paths: application/json: schema: $ref: ./clinic/models/ehrSettings.v1.yaml + '/v1/clinics/{clinicId}/settings/tide': + parameters: + - $ref: '#/components/parameters/clinicId' + get: + summary: Get Clinic TideReport Settings + tags: + - Clinics + - Internal + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: ./clinic/models/tide/tideSettings.v1.yaml + operationId: GetTideReportSettings + description: Returns TIDE Report related settings + x-internal: true + put: + summary: Update TideReport Settings + operationId: UpdateTideReportSettings + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: ./clinic/models/tide/tideSettings.v1.yaml + description: Update TIDE Report related settings for a clinic + tags: + - Clinics + - Internal + x-internal: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/updateTideReportSettings.v1' /v1/redox/match: post: summary: Match Clinic and Patient @@ -2409,6 +2456,16 @@ components: minLength: 1 tags: $ref: ./clinic/models/patientTagIds.v1.yaml + updateTideReportSettings.v1: + title: UpdateTideReportSettings + type: object + properties: + categories: + type: array + items: + $ref: ./clinic/models/tide/tideCategory.v1.yaml + required: + - categories addServiceAccount.v1: title: AddServiceAccount x-stoplight: diff --git a/reference/clinic/models/tide/tideCategory.v1.yaml b/reference/clinic/models/tide/tideCategory.v1.yaml new file mode 100644 index 00000000..e69de29b diff --git a/reference/clinic/models/tide/tideConfig.v1.yaml b/reference/clinic/models/tide/tideConfig.v1.yaml index 322664de..0568d164 100644 --- a/reference/clinic/models/tide/tideConfig.v1.yaml +++ b/reference/clinic/models/tide/tideConfig.v1.yaml @@ -1,6 +1,6 @@ type: object title: tideconfig.v1 -description: '' +description: 'Represents the config used at the time a TIDE report was generated.' properties: schemaVersion: description: TIDE schema version diff --git a/reference/clinic/models/tide/tideFilters.v1.yaml b/reference/clinic/models/tide/tideFilters.v1.yaml index a5bfd5a1..feda459f 100644 --- a/reference/clinic/models/tide/tideFilters.v1.yaml +++ b/reference/clinic/models/tide/tideFilters.v1.yaml @@ -1,6 +1,6 @@ type: object title: tidefilters.v1 -description: '' +description: 'Tide Filters represent the visual display of a TIDE report category.' properties: timeInVeryLowPercent: type: string @@ -23,9 +23,3 @@ properties: pattern: ^(>=|>|<=|<)\d\.\d\d?$ example: '>0.5' -required: - - timeInVeryLowPercent - - timeInAnyLowPercent - - dropInTimeInTargetPercent - - timeInTargetPercent - - timeCGMUsePercent \ No newline at end of file diff --git a/reference/clinic/models/tide/tideSettings.v1.yaml b/reference/clinic/models/tide/tideSettings.v1.yaml new file mode 100644 index 00000000..e69de29b diff --git a/reference/clinic/models/tide/tideThresholds.v1.yaml b/reference/clinic/models/tide/tideThresholds.v1.yaml new file mode 100644 index 00000000..712d89d9 --- /dev/null +++ b/reference/clinic/models/tide/tideThresholds.v1.yaml @@ -0,0 +1,25 @@ +type: object +title: tidethresholds.v1 +description: 'Represents the boundary values for a value to be considered low / high.' +properties: + highGlucoseThreshold: + description: Threshold used for determining if a value is high + type: number + x-go-type: float64 + veryHighGlucoseThreshold: + description: Threshold used for determining if a value is very high + type: number + x-go-type: float64 + lowGlucoseThreshold: + description: Threshold used for determining if a value is low + type: number + x-go-type: float64 + veryLowGlucoseThreshold: + description: Threshold used for determining if a value is very low + type: number + x-go-type: float64 +required: + - highGlucoseThreshold + - veryHighGlucoseThreshold + - lowGlucoseThreshold + - veryLowGlucoseThreshold From 8edb2be2ddcc130e733025d99dbd3c1b36c696ec Mon Sep 17 00:00:00 2001 From: lostlevels Date: Tue, 26 Aug 2025 15:54:24 -0700 Subject: [PATCH 2/6] Add tideSettings file. --- reference/clinic/models/tide/tideSettings.v1.yaml | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/reference/clinic/models/tide/tideSettings.v1.yaml b/reference/clinic/models/tide/tideSettings.v1.yaml index e69de29b..6155efd9 100644 --- a/reference/clinic/models/tide/tideSettings.v1.yaml +++ b/reference/clinic/models/tide/tideSettings.v1.yaml @@ -0,0 +1,14 @@ +type: object +title: tidesettings.v1 +description: 'Represents the TIDE report settings and preferences for a clinic.' +properties: + categories: + type: array + items: + $ref: ./tideCategory.v1.yaml + thresholds: + $ref: ./tideThresholds.v1.yaml + description: Thresholds for values to be considered low / high. Read-only as the values are hardcoded in the summary service. +required: + - categories + - thresholds From 69ddd874e9641985cf99193b486e42bd5e5d3a8d Mon Sep 17 00:00:00 2001 From: lostlevels Date: Tue, 26 Aug 2025 15:56:48 -0700 Subject: [PATCH 3/6] Add tideCategory. --- .../clinic/models/tide/tideCategory.v1.yaml | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/reference/clinic/models/tide/tideCategory.v1.yaml b/reference/clinic/models/tide/tideCategory.v1.yaml index e69de29b..0910da1e 100644 --- a/reference/clinic/models/tide/tideCategory.v1.yaml +++ b/reference/clinic/models/tide/tideCategory.v1.yaml @@ -0,0 +1,22 @@ +type: object +title: tidecategory.v1 +properties: + heading: + description: Name of the category. + type: string + field: + description: The target field to compare against. It is one of the two operands to the comparison operator. + type: string + value: + description: The reference value to compare the field against. + type: number + x-go-type: float64 + comparison: + description: The comparison operator to make between the field's value and the category's reference value, with field being the first operand and value being the second. `field comparison value` + type: string + enum: ['>', '>=', '<', '<=', '='] +required: + - heading + - comparison + - field + - value From d86eee7d2736d9aa7d944aaff4bd114a25c6510a Mon Sep 17 00:00:00 2001 From: lostlevels Date: Wed, 27 Aug 2025 11:54:18 -0700 Subject: [PATCH 4/6] Some commands for osx if realpath doens't support certain options. --- scripts/check_spec.sh | 9 +++++++-- scripts/generate_clinic.sh | 9 +++++++-- 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/scripts/check_spec.sh b/scripts/check_spec.sh index 3234ca4b..37a3224c 100755 --- a/scripts/check_spec.sh +++ b/scripts/check_spec.sh @@ -3,8 +3,13 @@ set -euo pipefail SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd ) -TOOLS_BIN=$(realpath --canonicalize-existing "$SCRIPT_DIR/../tools/bin") -NPM_BIN=$(realpath --canonicalize-existing "$SCRIPT_DIR/../node_modules/.bin") +if [[ $OSTYPE =~ darwin ]] && command -v grealpath &> /dev/null; then + TOOLS_BIN=$(grealpath --canonicalize-existing "$SCRIPT_DIR/../tools/bin") + NPM_BIN=$(grealpath --canonicalize-existing "$SCRIPT_DIR/../node_modules/.bin") +else + TOOLS_BIN=$(realpath --canonicalize-existing "$SCRIPT_DIR/../tools/bin") + NPM_BIN=$(realpath --canonicalize-existing "$SCRIPT_DIR/../node_modules/.bin") +fi PATH=$TOOLS_BIN:$NPM_BIN:$PATH trace() { diff --git a/scripts/generate_clinic.sh b/scripts/generate_clinic.sh index 973ff4f1..543b8c95 100755 --- a/scripts/generate_clinic.sh +++ b/scripts/generate_clinic.sh @@ -3,8 +3,13 @@ set -eou pipefail SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd ) -TOOLS_BIN=$(realpath --canonicalize-existing "$SCRIPT_DIR/../tools/bin") -NPM_BIN=$(realpath --canonicalize-existing "$SCRIPT_DIR/../node_modules/.bin") +if [[ $OSTYPE =~ darwin ]] && command -v grealpath &> /dev/null; then + TOOLS_BIN=$(grealpath --canonicalize-existing "$SCRIPT_DIR/../tools/bin") + NPM_BIN=$(grealpath --canonicalize-existing "$SCRIPT_DIR/../node_modules/.bin") +else + TOOLS_BIN=$(realpath --canonicalize-existing "$SCRIPT_DIR/../tools/bin") + NPM_BIN=$(realpath --canonicalize-existing "$SCRIPT_DIR/../node_modules/.bin") +fi PATH=$TOOLS_BIN:$NPM_BIN:$PATH trace() { From 884bad953f9de0b38d4bceb7bd26dba70e4483c5 Mon Sep 17 00:00:00 2001 From: lostlevels Date: Wed, 27 Aug 2025 15:06:02 -0700 Subject: [PATCH 5/6] Add tide category available names. --- reference/clinic.v1.yaml | 6 +++--- reference/clinic/models/tide/tideCategoryName.v1.yaml | 10 ++++++++++ 2 files changed, 13 insertions(+), 3 deletions(-) create mode 100644 reference/clinic/models/tide/tideCategoryName.v1.yaml diff --git a/reference/clinic.v1.yaml b/reference/clinic.v1.yaml index 7a5460e8..fffeaf06 100644 --- a/reference/clinic.v1.yaml +++ b/reference/clinic.v1.yaml @@ -272,7 +272,7 @@ paths: - schema: type: array items: - type: string + $ref: ./clinic/models/tide/tideCategoryName.v1.yaml in: query name: categories description: Comma-separated list of category names to include in the report. Omit to include all. @@ -1825,7 +1825,7 @@ paths: parameters: - $ref: '#/components/parameters/clinicId' get: - summary: Get Clinic TideReport Settings + summary: Get Clinic TIDE report settings tags: - Clinics - Internal @@ -1840,7 +1840,7 @@ paths: description: Returns TIDE Report related settings x-internal: true put: - summary: Update TideReport Settings + summary: Update TIDE report settings operationId: UpdateTideReportSettings responses: '200': diff --git a/reference/clinic/models/tide/tideCategoryName.v1.yaml b/reference/clinic/models/tide/tideCategoryName.v1.yaml new file mode 100644 index 00000000..df510b93 --- /dev/null +++ b/reference/clinic/models/tide/tideCategoryName.v1.yaml @@ -0,0 +1,10 @@ +title: categoryname.v1.yaml +description: 'Allowed TIDE category names' +type: string +enum: + - timeInVeryLowPercent + - timeInAnyLowPercent + - dropInTimeInTargetPercent + - timeInTargetPercent + - timeCGMUsePercent + From 9e016c5c2e3eafcc718cbb4da7a41db7946a1eff Mon Sep 17 00:00:00 2001 From: lostlevels Date: Tue, 2 Sep 2025 17:13:48 -0700 Subject: [PATCH 6/6] Remove tide filters from response and replace w/ categories as all filters are just categories. --- reference/clinic.v1.yaml | 21 +++++- .../clinic/models/tide/tideCategory.v1.yaml | 51 +++++++++---- .../models/tide/tideCategoryName.v1.yaml | 10 --- .../clinic/models/tide/tideConfig.v1.yaml | 8 +- .../clinic/models/tide/tideSettings.v1.yaml | 2 +- .../models/tide/tideSummaryField.v1.yaml | 73 +++++++++++++++++++ 6 files changed, 133 insertions(+), 32 deletions(-) delete mode 100644 reference/clinic/models/tide/tideCategoryName.v1.yaml create mode 100644 reference/clinic/models/tide/tideSummaryField.v1.yaml diff --git a/reference/clinic.v1.yaml b/reference/clinic.v1.yaml index fffeaf06..75b48bf2 100644 --- a/reference/clinic.v1.yaml +++ b/reference/clinic.v1.yaml @@ -270,9 +270,13 @@ paths: name: lastDataCutoff description: Inclusive - schema: - type: array - items: - $ref: ./clinic/models/tide/tideCategoryName.v1.yaml + oneOf: + - type: array + items: + $ref: '#/components/schemas/predefinedCategoryName.v1' + - type: array + items: + type: string in: query name: categories description: Comma-separated list of category names to include in the report. Omit to include all. @@ -2539,6 +2543,17 @@ components: description: Optional action to be performed when a unique match has been found required: - criteria + predefinedCategoryName.v1: + type: string + enum: + - timeInVeryLowPercent + - timeInAnyLowPercent + - dropInTimeInTargetPercent + - timeInTargetPercent + - timeCGMUsePercent + - meetingTargets + - noData + description: Existing default pre-defined TIDE report categories. securitySchemes: sessionToken: name: x-tidepool-session-token diff --git a/reference/clinic/models/tide/tideCategory.v1.yaml b/reference/clinic/models/tide/tideCategory.v1.yaml index 0910da1e..f4e2d288 100644 --- a/reference/clinic/models/tide/tideCategory.v1.yaml +++ b/reference/clinic/models/tide/tideCategory.v1.yaml @@ -1,22 +1,43 @@ type: object title: tidecategory.v1 properties: - heading: + name: description: Name of the category. type: string - field: - description: The target field to compare against. It is one of the two operands to the comparison operator. - type: string - value: - description: The reference value to compare the field against. - type: number - x-go-type: float64 comparison: - description: The comparison operator to make between the field's value and the category's reference value, with field being the first operand and value being the second. `field comparison value` - type: string - enum: ['>', '>=', '<', '<=', '='] + description: Describes a comparison filter against a summary field. + type: object + properties: + summaryField: + description: Summary field to compare against. + $ref: './tideSummaryField.v1.yaml' + op: + description: Comparison operator. + type: string + enum: ['>', '>=', '<', '<=', '='] + value: + description: Value to compare summaryField against. + required: + - summaryField + - op + - value + sort: + description: Describes a sorting operation against a summary field. + type: object + properties: + summaryField: + description: Summary field to use as a sort key. + $ref: './tideSummaryField.v1.yaml' + direction: + description: Sort direction. + type: string + enum: ['ascending', 'descending'] + required: + - summaryField + - direction + priority: + description: Priority of category to use when iterating against a list of categories when generating a TIDE report with a lower value having higher priority. This is used to because of a TIDE report patient limit so higher priority categories will be queried first. + type: integer required: - - heading - - comparison - - field - - value + - name + - sort diff --git a/reference/clinic/models/tide/tideCategoryName.v1.yaml b/reference/clinic/models/tide/tideCategoryName.v1.yaml deleted file mode 100644 index df510b93..00000000 --- a/reference/clinic/models/tide/tideCategoryName.v1.yaml +++ /dev/null @@ -1,10 +0,0 @@ -title: categoryname.v1.yaml -description: 'Allowed TIDE category names' -type: string -enum: - - timeInVeryLowPercent - - timeInAnyLowPercent - - dropInTimeInTargetPercent - - timeInTargetPercent - - timeCGMUsePercent - diff --git a/reference/clinic/models/tide/tideConfig.v1.yaml b/reference/clinic/models/tide/tideConfig.v1.yaml index 0568d164..d6439849 100644 --- a/reference/clinic/models/tide/tideConfig.v1.yaml +++ b/reference/clinic/models/tide/tideConfig.v1.yaml @@ -33,8 +33,11 @@ properties: x-go-type: float64 tags: $ref: ../patientTagIds.v1.yaml - filters: - $ref: ./tideFilters.v1.yaml + categories: + description: Categories that were used during report generation. + type: array + items: + $ref: ./tideCategory.v1.yaml required: - schemaVersion @@ -46,4 +49,3 @@ required: - lowGlucoseThreshold - veryLowGlucoseThreshold - tags - - filters diff --git a/reference/clinic/models/tide/tideSettings.v1.yaml b/reference/clinic/models/tide/tideSettings.v1.yaml index 6155efd9..504050c4 100644 --- a/reference/clinic/models/tide/tideSettings.v1.yaml +++ b/reference/clinic/models/tide/tideSettings.v1.yaml @@ -8,7 +8,7 @@ properties: $ref: ./tideCategory.v1.yaml thresholds: $ref: ./tideThresholds.v1.yaml - description: Thresholds for values to be considered low / high. Read-only as the values are hardcoded in the summary service. + description: Thresholds for values to be considered low / high. Read-only as the values are hardcoded in the platform summary service. required: - categories - thresholds diff --git a/reference/clinic/models/tide/tideSummaryField.v1.yaml b/reference/clinic/models/tide/tideSummaryField.v1.yaml new file mode 100644 index 00000000..63722c4d --- /dev/null +++ b/reference/clinic/models/tide/tideSummaryField.v1.yaml @@ -0,0 +1,73 @@ +title: tidesummaryfield.v1.yaml +description: Available summary fields for a TIDE report category to filter / sort against. +type: string +enum: + - averageDailyRecords + - averageDailyRecordsDelta + - averageGlucoseMmol + - averageGlucoseMmolDelta + - coefficientOfVariation + - coefficientOfVariationDelta + - daysWithData + - daysWithDataDelta + - hoursWithData + - hoursWithDataDelta + - standardDeviation + - standardDeviationDelta + - timeCGMUseMinutes + - timeCGMUseMinutesDelta + - timeCGMUsePercent + - timeCGMUsePercentDelta + - timeCGMUseRecords + - timeCGMUseRecordsDelta + - timeInAnyHighMinutes + - timeInAnyHighMinutesDelta + - timeInAnyHighPercent + - timeInAnyHighPercentDelta + - timeInAnyHighRecords + - timeInAnyHighRecordsDelta + - timeInAnyLowMinutes + - timeInAnyLowMinutesDelta + - timeInAnyLowPercent + - timeInAnyLowPercentDelta + - timeInAnyLowRecords + - timeInAnyLowRecordsDelta + - timeInExtremeHighMinutes + - timeInExtremeHighMinutesDelta + - timeInExtremeHighPercent + - timeInExtremeHighPercentDelta + - timeInExtremeHighRecords + - timeInExtremeHighRecordsDelta + - timeInHighMinutes + - timeInHighMinutesDelta + - timeInHighPercent + - timeInHighPercentDelta + - timeInHighRecords + - timeInHighRecordsDelta + - timeInLowMinutes + - timeInLowMinutesDelta + - timeInLowPercent + - timeInLowPercentDelta + - timeInLowRecords + - timeInLowRecordsDelta + - timeInTargetMinutes + - timeInTargetMinutesDelta + - timeInTargetPercent + - timeInTargetPercentDelta + - timeInTargetRecords + - timeInTargetRecordsDelta + - timeInVeryHighMinutes + - timeInVeryHighMinutesDelta + - timeInVeryHighPercent + - timeInVeryHighPercentDelta + - timeInVeryHighRecords + - timeInVeryHighRecordsDelta + - timeInVeryLowMinutes + - timeInVeryLowMinutesDelta + - timeInVeryLowPercent + - timeInVeryLowPercentDelta + - timeInVeryLowRecords + - timeInVeryLowRecordsDelta + - totalRecords + - totalRecordsDelta +