Health Gorilla Lab Order Ingest

The HealthGorillaLabOrderIngest effect creates a Canvas LabOrder plus its LabTest rows for an order that was placed outside Canvas — for example, by a partner on its own Health Gorilla tenant. Canvas records the order so it shows up in the chart, but the order’s hg_request_result field is set to a partner-supplied skip-send marker so Canvas’s send-to-Health-Gorilla worker treats the order as already-sent and never forwards it.

Typical use is from a SimpleAPI route the partner POSTs to when they place a standing or recurring order on their side.

Build a HealthGorillaLabOrderIngest with the attributes you want to set, then return its apply() from your handler.

Methods #

apply() → Effect #

Creates the lab order and its tests, as described under Behavior.

  • patient_id, ordering_provider_npi, note_id, ontology_lab_partner, date_ordered, hg_request_result, and at least one entry in test_codes are required.
  • The patient and note must exist, and a staff member must have the NPI ordering_provider_npi.

Behavior #

Canvas processes the effect in a single transaction:

  1. Resolves Patient (by id), Staff (by NPI), and Note (by external id).
  2. Creates a LabOrder with hg_request_result set non-empty so the send-to-HG worker leaves it alone.
  3. Creates one LabTest row per HG order code in test_codes. Test names are filled from the HG ontology when available.

Each LabTest is created with status RECEIVED, since externally-originated orders are past the Canvas send pipeline.

Attributes #

| Attribute | Type | Description | Required | | ———————– | ———– | —————————————————————————————————- | ——– | | patient_id | str | The id of the patient. | Yes | | ordering_provider_npi | str | NPI used to look up the staff record. | Yes | | note_id | str | The id of the note. Lab orders require an associated note. | Yes | | ontology_lab_partner | str | Ontology lab partner name (for example "Quest Diagnostics" or "LabCorp"). | Yes | | date_ordered | datetime | When the order was authored on the partner side. | Yes | | hg_request_result | str | Skip-send marker. Convention is the partner’s HG RequestGroup URL or id so Canvas can correlate later. Any non-empty value works. | Yes | | test_codes | list[str] | One or more HG order codes. One LabTest row is created per entry. | Yes | | external_id | str | Stored on LabOrder.healthgorilla_id; useful for partner-side dedup. | No | | comment | str | Stored on LabOrder.comment. | No |

Example #

from datetime import datetime, UTC

from canvas_sdk.effects.lab_order import HealthGorillaLabOrderIngest
from canvas_sdk.effects.simple_api import JSONResponse, Response
from canvas_sdk.handlers.simple_api import APIKeyCredentials, SimpleAPIRoute


class StandingLabOrdersAPI(SimpleAPIRoute):
    PATH = "/standing-lab-orders"

    def authenticate(self, credentials: APIKeyCredentials) -> bool:
        return credentials.key == self.secrets["ingest-api-key"]

    def post(self) -> list[Response]:
        body = self.request.json()
        return [
            HealthGorillaLabOrderIngest(
                patient_id=body["patient_id"],
                ordering_provider_npi=body["ordering_provider_npi"],
                note_id=body["note_id"],
                ontology_lab_partner=body["ontology_lab_partner"],
                date_ordered=datetime.fromisoformat(body["date_ordered"]),
                hg_request_result=body["hg_request_result"],
                test_codes=body["test_codes"],
                external_id=body.get("external_id", ""),
            ).apply(),
            JSONResponse({"external_id": body["external_id"]}, status_code=201),
        ]

Related #

Questions? Create an issue.
On this page