diff --git a/CHANGELOG.md b/CHANGELOG.md index 7ae44875d..353e7d435 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,7 +19,7 @@ stay under for any nutrient on the energy card; the chart draws your number instead of the reference. Targets travel in the full backup and are read and set through `GET` and `PATCH /api/nutrients/targets`. (#1402) -- Lab results from Apple Health's Health Records now land in Labs. An Apple Health export used to skip every clinical record; the lab results among them are now read, matched to your existing markers (by name, alias or LOINC code, with a reading in another unit converted and the printed value kept), and filed under their panel. A result like "<0.5 mg/L" is kept as printed, a specific gravity, pH or INR sent without a unit is read as a plain number, the report's own reference range comes along, and preliminary or withdrawn results are left out. Importing the same results again writes nothing, a result you delete stays deleted (also when you delete its whole marker, long after the deletion, and across a backup restore), and a reading you already typed or scanned is not doubled. If you imported an archive before, upload it once more to pick up its lab results. For the iOS app, `POST /api/labs/fhir-batch` takes the same results straight from HealthKit. Thanks to @camiracode for asking for this. (#1400) +- Lab results from Apple Health's Health Records now land in Labs. An Apple Health export used to skip every clinical record; the lab results among them are now read, matched to your existing markers (by name, alias or LOINC code, with a reading in another unit converted and the printed value kept), and filed under their panel. A result like "<0.5 mg/L" is kept as printed, a specific gravity, pH or INR sent without a unit is read as a plain number, the report's own reference range comes along, and preliminary or withdrawn results are left out. A result your provider later marks as entered in error is not removed once it is in HealthLog; delete it there if it should go. Importing the same results again writes nothing, a result you delete stays deleted (also when you delete its whole marker, long after the deletion, and across a backup restore), and a reading you already typed or scanned is not doubled. If you imported an archive before, upload it once more to pick up its lab results. For the iOS app, `POST /api/labs/fhir-batch` takes the same results straight from HealthKit. Thanks to @camiracode for asking for this. (#1400) ### Changed diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml index 6955b58d6..aef1c9077 100644 --- a/docs/api/openapi.yaml +++ b/docs/api/openapi.yaml @@ -78308,12 +78308,13 @@ components: holds it, under the same identity (deleted readings included, also once the reading or its whole marker is gone, so a deleted result stays deleted) or as the same reading on the same day from another source. `skipped`: not a reading HealthLog keeps, with `reason` `not_observation` | `not_lab` (no category names a lab; a code, display - or text containing `lab` in any case counts) | `not_final` (preliminary; it is taken once final) | `withdrawn` | - `panel_header` | `no_value` | `unsupported_value` | `no_date` | `future_date` | `invalid_date` | `too_large` (a - resource over 256 KiB). `failed`: a reading that could not be stored, with `reason` `missing_unit` (a number - without a unit; a specific gravity, a pH or an INR, known by its LOINC code, is read as the unity `1` instead) | - `unit_mismatch` (the account's marker is in a unit this one does not convert into) | `text_too_long` | - `write_failed` (transient: send it again)." + or text containing `lab` in any case counts) | `not_final` (preliminary; it is taken once final) | `withdrawn` + (entered in error or cancelled; a reading already stored from an earlier version of the result is not removed, + delete it through `DELETE /api/labs/{id}`) | `panel_header` | `no_value` | `unsupported_value` | `no_date` | + `future_date` | `invalid_date` | `too_large` (a resource over 256 KiB). `failed`: a reading that could not be + stored, with `reason` `missing_unit` (a number without a unit; a specific gravity, a pH or an INR, known by its + LOINC code, is read as the unity `1` instead) | `unit_mismatch` (the account's marker is in a unit this one does + not convert into) | `text_too_long` | `write_failed` (transient: send it again)." LabOverviewEnvelope: type: object properties: diff --git a/docs/integrations/apple-health.md b/docs/integrations/apple-health.md index 1df0e6ede..f16a47ab5 100644 --- a/docs/integrations/apple-health.md +++ b/docs/integrations/apple-health.md @@ -140,14 +140,21 @@ temporary files. The auxiliary reader enforces limits before and during decompression: -- at most 20,000 total archive members and 2,000 ECG CSV members; +- at most 200,000 archive members of any kind (the same ceiling for the + ECG, workout-route and Health Records passes) and 2,000 ECG CSV members; - at most 16 MiB per decompressed ECG CSV and 512 MiB across all ECG CSVs; - at most a 200:1 declared compression ratio; and - at most 2,000,000 waveform samples per recording. -Encrypted ZIP members, unsupported compression, unsafe or duplicate -paths, forged size metadata, malformed timestamps or samples, and -limit overruns are rejected. An ECG failure is fail-soft: valid +Unsafe or duplicate paths and a malformed archive end the pass; so does +a running total over its limit. An ECG CSV that is encrypted, uses an +unsupported compression or breaks a per-file limit (including a +compressed size over the per-file limit, whatever the size metadata +says) fails on its own, and the other recordings are still read. The +per-file limits apply only to the files a pass reads: a large file of +another kind, or a route or Health Records file the export does not +reference, is skipped without being checked. Malformed timestamps or +samples are rejected per recording. An ECG failure is fail-soft: valid `export.xml` measurements and workouts still commit, while the terminal result reports only `discovered/imported/updated/skipped/failed` ECG counts. It never @@ -179,17 +186,30 @@ turns each final laboratory Observation into a lab reading: value kept beside it; - a result with a comparator (`<0.5 mg/L`) is kept as text, as printed; - the report's own reference range is kept with the reading; +- a specific gravity, a pH or an INR sent as a number without a unit + (known by its LOINC code) is kept as a plain number; any other number + without a unit is refused; - a panel header is not a reading, but its members carry its name; - preliminary results, withdrawn results and other categories (vital - signs, for instance) are skipped. + signs, for instance) are skipped. A category counts as laboratory when + its code, display or text contains "lab", whatever the spelling; +- a file over a size limit fails on its own; the other files are still + read. Each reading keeps an identity built from the issuing institution and the record identifier (a digest, `lab_results.external_id`). Uploading the archive again writes nothing new, a result deleted in HealthLog -stays deleted, and the iOS app sending the same result through +stays deleted (also after its whole marker is deleted, after the +deleted reading is purged, and across a backup restore: the identity is +kept in `lab_result_import_keys`), and the iOS app sending the same result through `POST /api/labs/fhir-batch` is recognised as the same reading. A reading already entered by hand, scanned or imported from a CSV on the -same day with the same value is not written twice. The pass is +same day with the same value is not written twice. The first stored +version of a result is the one kept: an amended result arriving under +the same identity is a duplicate, and a result later marked entered in +error or cancelled at the provider is skipped as withdrawn but does not +remove the reading already stored. Delete it in HealthLog if it should +go. The pass is fail-soft like the ECG pass, and the job result carries only `discovered/imported/duplicate/skipped/failed` lab counts. diff --git a/src/lib/openapi/routes/labs.ts b/src/lib/openapi/routes/labs.ts index 8fcf053f3..31efbdaad 100644 --- a/src/lib/openapi/routes/labs.ts +++ b/src/lib/openapi/routes/labs.ts @@ -205,7 +205,7 @@ const fhirLabRecordResult = z .meta({ id: "FhirLabRecordResult", description: - "One record's outcome, by its position in the request. `inserted`: written. `duplicate`: the record already holds it, under the same identity (deleted readings included, also once the reading or its whole marker is gone, so a deleted result stays deleted) or as the same reading on the same day from another source. `skipped`: not a reading HealthLog keeps, with `reason` `not_observation` | `not_lab` (no category names a lab; a code, display or text containing `lab` in any case counts) | `not_final` (preliminary; it is taken once final) | `withdrawn` | `panel_header` | `no_value` | `unsupported_value` | `no_date` | `future_date` | `invalid_date` | `too_large` (a resource over 256 KiB). `failed`: a reading that could not be stored, with `reason` `missing_unit` (a number without a unit; a specific gravity, a pH or an INR, known by its LOINC code, is read as the unity `1` instead) | `unit_mismatch` (the account's marker is in a unit this one does not convert into) | `text_too_long` | `write_failed` (transient: send it again).", + "One record's outcome, by its position in the request. `inserted`: written. `duplicate`: the record already holds it, under the same identity (deleted readings included, also once the reading or its whole marker is gone, so a deleted result stays deleted) or as the same reading on the same day from another source. `skipped`: not a reading HealthLog keeps, with `reason` `not_observation` | `not_lab` (no category names a lab; a code, display or text containing `lab` in any case counts) | `not_final` (preliminary; it is taken once final) | `withdrawn` (entered in error or cancelled; a reading already stored from an earlier version of the result is not removed, delete it through `DELETE /api/labs/{id}`) | `panel_header` | `no_value` | `unsupported_value` | `no_date` | `future_date` | `invalid_date` | `too_large` (a resource over 256 KiB). `failed`: a reading that could not be stored, with `reason` `missing_unit` (a number without a unit; a specific gravity, a pH or an INR, known by its LOINC code, is read as the unity `1` instead) | `unit_mismatch` (the account's marker is in a unit this one does not convert into) | `text_too_long` | `write_failed` (transient: send it again).", }); const fhirLabBatchResponse = z