[BACK-3970] Add spec for configurable TIDE report categories.

reference/clinic.v1.yaml

@@ -269,6 +269,19 @@
           in: query
           name: lastDataCutoff
           description: Inclusive
+        - schema:
+            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.
+          style: form
+          explode: false
   '/v1/clinics/{clinicId}/patients':
     parameters:
       - $ref: '#/components/parameters/clinicId'
@@ -1812,6 +1825,44 @@
           application/json:
             schema:
               $ref: ./clinic/models/ehrSettings.v1.yaml
+  '/v1/clinics/{clinicId}/settings/tide':
+    parameters:
+      - $ref: '#/components/parameters/clinicId'
+    get:
+      summary: Get Clinic TIDE report 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 TIDE report 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
@@ -1996,7 +2047,7 @@
 
         https://sandbox.xealth.io/app/api-docs#tag/Digital-Care/paths/preorder/post
   /v1/xealth/programs:
     put:
       summary: Get Programs
       operationId: XealthGetPrograms
       responses:
@@ -2013,7 +2064,7 @@
       responses:
         '200':
           description: OK
       description: ''
       tags:
         - Clinics
         - Internal
@@ -2025,7 +2076,7 @@
       responses:
         '200':
           description: OK
       description: ''
       tags:
         - Clinics
         - Internal
@@ -2409,6 +2460,16 @@
           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:
@@ -2482,6 +2543,17 @@
           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

reference/clinic/models/tide/tideCategory.v1.yaml

@@ -0,0 +1,43 @@
+type: object
+title: tidecategory.v1
+properties:
+  name:
+    description: Name of the category.
+    type: string
+  comparison:
+    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:
+  - name
+  - sort

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
@@ -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

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

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 platform summary service.
+required:
+  - categories
+  - thresholds

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
+

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

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() {

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() {