From b415d394aecce292c3e9bdf36ceb9c4439672259 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= Date: Tue, 17 Nov 2026 21:28:57 +0100 Subject: [PATCH] docs(labs): say what a later entered-in-error status does to a stored result A Health Records result the provider later marks entered in error is skipped as withdrawn, but a reading already stored from an earlier version stays until it is deleted in HealthLog. Say so in the changelog, the import guide and the batch route's contract, and bring the guide's archive limits and lab notes in line with the current reader. --- CHANGELOG.md | 2 +- docs/api/openapi.yaml | 13 ++++++------ docs/integrations/apple-health.md | 34 ++++++++++++++++++++++++------- src/lib/openapi/routes/labs.ts | 2 +- 4 files changed, 36 insertions(+), 15 deletions(-) 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