Huli FHIR Core Implementation Guide (R4)
0.1.0 - Release
Huli FHIR Core Implementation Guide (R4) - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
HuliServiceRequest carries a study or lab order placed against a Huli patient
(an order line of a service order). The Public API supports read, search,
create, and update for this resource. This surface is the FHIR projection of the
clinical Plan section ("Plan / Órdenes") of an encounter.
Create and update both route through the same practice service-order service the Huli application uses, so a public write runs the platform's clinical rules rather than writing straight to the database:
subject) and, when present, the encounter
(encounter) inside the authenticated organization; cross-organization references
are rejected with 422.409 Conflict), matching the
in-app behavior.code.PUT /fhir/R4/ServiceRequest/{id} is a full-resource replace with
read-then-merge semantics: the FHIR-owned fields (priority, the primary
code + category, reasonCode, note) overlay the stored order, while
app-only fields the FHIR projection does not carry are preserved — the
requisition grouping, the requesting practitioner, and the per-study clinical
order data (specimen requirements, body site, performer instructions, referral
details) all survive the update. reasonCode and note follow faithful
replace semantics (absent means removed); priority is the one exception — a
body that omits it preserves the stored value instead of resetting it to
routine, because priority is a clinical triage decision an integration that
does not model it must not silently downgrade. The update is draft-gated: an order whose
backing clinical document is already signed or cancelled cannot be modified
(409 Conflict, HPB-00135), matching the in-app immutability rule. An order
holding more than one study is read-only on this surface (409, HPB-00136)
— a replace would drop clinician-authored studies. subject and encounter
are immutable: a body that differs from the stored bindings is rejected
(422). Reads and writes carry a weak ETag; supply it as If-Match for
optimistic concurrency — a stale validator is rejected 409 (HPB-00103),
re-checked against the locked row inside the write transaction.
Every operation requires the SMART scope system/ServiceRequest.rs (read /
search) or system/ServiceRequest.cru (create / read / update) AND the
corresponding practice permission on the api key's user. A valid scope on a key
whose user lacks the permission is denied with 403.
ServiceRequest is clinical-sensitive and therefore BAA-gated: an api
key without an executed Business Associate Agreement cannot obtain these scopes.
See Data handling and compliance for
the integrator BAA obligations.
| Huli field | FHIR path | Cardinality | Must Support | Notes |
|---|---|---|---|---|
id_service_order |
ServiceRequest.id |
1..1 | – | UUID, allocated server-side; client-supplied IDs are rejected on POST |
modified_on |
ServiceRequest.meta.lastUpdated |
0..1 | – | Set by the platform |
| – | ServiceRequest.meta.profile[0] |
0..1 | – | Always https://fhir.huli.ai/r4/StructureDefinition/HuliServiceRequest |
| Huli concept | FHIR ServiceRequest.status |
Notes |
|---|---|---|
| active | active |
Default for a newly placed order |
| on hold | on-hold |
Temporarily suspended |
| completed | completed |
Order fulfilled |
| revoked | revoked |
Withdrawn before fulfilment |
| entered in error | entered-in-error |
Void marker |
On read, the revoked row maps from the Huli "cancelled" request status (FHIR
R4 ServiceRequest.status has no cancelled). On write (create and update), a
status other than active is rejected (400): the write paths persist
only active, and lifecycle transitions (revoke, complete) are not exposed
through this surface. An absent status defaults to active.
| FHIR path | Cardinality | Notes |
|---|---|---|
ServiceRequest.intent |
1..1 | Always emitted as order. The Public API does not model proposal / plan / directive. |
Any intent is accepted and normalized to order on write — it is not rejected.
| FHIR path | Notes |
|---|---|
ServiceRequest.category[0].coding[0].code |
One of laboratory, clinical, procedure, referral |
ServiceRequest.category[0].text |
Display string for the category |
A category outside the four-value set above is rejected 400.
| FHIR path | Notes |
|---|---|
ServiceRequest.priority |
One of routine, urgent, asap, stat. Absent on create: defaults to routine. Absent on update: the stored value is preserved. |
| FHIR path | Notes |
|---|---|
ServiceRequest.code.coding[0].display |
Display name of the ordered service; required on write |
ServiceRequest.code.coding[0].code |
Service code, when the service is catalog-coded |
ServiceRequest.code.text |
Mirror of the display for human-readable rendering |
The single code is the order's primary item. See
Parity limitations for multi-item orders.
| FHIR path | Cardinality | Must Support | Notes |
|---|---|---|---|
ServiceRequest.subject |
1..1 | Yes | Reference(HuliPatient); required on read and write |
ServiceRequest.encounter |
0..1 | Yes | Reference(HuliEncounter); the encounter the order was placed in |
References passed on create must resolve inside the authenticated organization;
cross-organization references are rejected with 422.
| FHIR path | Notes |
|---|---|
ServiceRequest.orderDetail[] |
Read-only. Carries the extra items of a multi-item app order; each entry is a CodeableConcept for one additional ordered service. Empty for single-item orders. |
orderDetail[] is emitted on read only — it is not consumed on write (see
Parity limitations).
| FHIR path | Huli concept | Notes |
|---|---|---|
ServiceRequest.reasonCode[0].text |
Reason | Free-text indication for the order |
ServiceRequest.note[0].text |
Notes | Free-text order notes |
The Public API advertises the following search parameters on
GET /fhir/R4/ServiceRequest:
| Parameter | Type | Notes |
|---|---|---|
_id |
token | Direct lookup by ServiceRequest.id |
patient |
reference | Reference(HuliPatient); logical id or full reference |
encounter |
reference | Reference(HuliEncounter) |
_count |
number | Page size |
_cursor |
string | Opaque cursor returned in Bundle.link[rel=next] |
A patient or encounter parameter is required. status and category are
not search parameters in v1 — the search filters by patient/encounter only.
Search responses are returned as a FHIR Bundle of type searchset with
cursor-based pagination.
ServiceRequest maps to one app
service order with a single primary item (code). An app order created
in-app with multiple items reads back with the first item under code and the
extras under orderDetail[] (read-only).orderDetail[] (extra
items) is rejected 400, and a PUT targeting an order that already holds
multiple studies is rejected 409 (HPB-00136). Place each additional item as
its own ServiceRequest, or use the app to assemble a multi-item order.| Huli concept | Reason it is not on ServiceRequest |
|---|---|
| Order print/PDF rendering | Operational artifact; not part of the resource contract |
| Result attachments / report linkage | DiagnosticReport is not in this IG |
| Ordering-provider credential block | Carried on Practitioner, not on the order line |