Admin: Automated edit (via update-page on MediaWiki MCP Server)

2026-07-06T04:05:41Z

Automated edit (via update-page on MediaWiki MCP Server)

← Older revision		Revision as of 09:35, 6 July 2026
Line 353:		Line 353:
	* [[References/Location]] — facility locations the request applies to		* [[References/Location]] — facility locations the request applies to
	* [[References/User & Skills\|User]] — requester / audit users		* [[References/User & Skills\|User]] — requester / audit users

			{{Navbox clinical}}

	{{Related}}		{{Related}}
			Wiki: ohcnwiki.tellmey.fyi

Admin: OHC identity seed

2026-07-04T22:44:32Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=clinical
|title=Service Request
|order=12
|introduced=3.0
|fhir=ServiceRequest
|model=ServiceRequest
}}

A <code>ServiceRequest</code> is an order or proposal to perform an action — clinical or otherwise — for a patient (FHIR <code>ServiceRequest</code>). It drives the creation of specimens, diagnostic reports, observations, and procedures, each of which links back to the originating request. Care implements a minimal subset of the FHIR spec.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/service_request.py <code>care/emr/models/service_request.py</code>]
* Resource spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/service_request/spec.py <code>care/emr/resources/service_request/spec.py</code>]

The Django model is only storage: several columns are opaque <code>JSONField</code>s and free-text <code>CharField</code>s. Their real structure, enums, bound value sets, and read/write API schemas live in the Pydantic resource specs (<code>care/emr/resources/service_request/spec.py</code>). Both layers are covered below.

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>ServiceRequest</code>
| An order or proposal to perform an action for a patient
|}

<code>ServiceRequest</code> extends <code>EMRBaseModel</code>, the shared Care EMR base that supplies <code>external_id</code>, audit fields <code>created_by</code>/<code>updated_by</code>, <code>created_date</code>/<code>modified_date</code>, <code>meta</code>, and soft-delete semantics — see [[References/Base models & conventions|Base model]].

== <code>ServiceRequest</code> fields ==

=== Request definition ===

{| class="wikitable"
|-
! Field
! Model type
! Spec type / shape
! Notes
|-
| <code>title</code>
| <code>CharField(1024)</code>
| <code>str</code>
| Human-readable summary. Required on create, optional on update.
|-
| <code>category</code>
| <code>CharField(255)</code>
| <code>ActivityDefinitionCategoryOptions</code> enum
| Coded category. Required on create. See [[#category-values
|-
| <code>status</code>
| <code>CharField(255)</code>
| <code>ServiceRequestStatusChoices</code> enum
| Lifecycle status. Required on create. See [[#status-values
|-
| <code>intent</code>
| <code>CharField(255)</code>
| <code>ServiceRequestIntentChoices</code> enum
| Required on create. See [[#intent-values
|-
| <code>priority</code>
| <code>CharField(255)</code>
| <code>ServiceRequestPriorityChoices</code> enum
| Required on create. See [[#priority-values
|-
| <code>do_not_perform</code>
| <code>BooleanField</code>
| <code>bool | None</code>
| <code>True</code> flags the service/procedure as explicitly not to be performed. Model default <code>False</code>; spec default <code>None</code>, so it's omitted from writes unless set.
|-
| <code>code</code>
| <code>JSONField</code> (nullable)
| <code>Coding</code> bound to <code>activity-definition-procedure-code</code>
| The requested service/procedure. Required on create. A single <code>Coding</code>, not a <code>CodeableConcept</code>, validated against the bound value set.
|-
| <code>body_site</code>
| <code>JSONField</code> (nullable)
| <code>Coding</code> bound to <code>system-body-site-observation</code>, optional
| Coded location on the body. A single <code>Coding</code>, validated against the bound value set.
|}

A bound <code>Coding</code> (<code>ValueSetBoundCoding</code>) has the shape:

<syntaxhighlight lang="json">{
"system": "<uri | null>",
"version": "<str | null>",
"code": "<str>", // required; must resolve in the bound value set
"display": "<str | null>"
}</syntaxhighlight>
=== Clinical detail ===

{| class="wikitable"
|-
! Field
! Model type
! Spec type
! Notes
|-
| <code>note</code>
| <code>TextField</code> (nullable)
| <code>str | None</code>
| Free-text comments.
|-
| <code>patient_instruction</code>
| <code>TextField</code> (nullable)
| <code>str | None</code>
| Instructions surfaced to the patient.
|-
| <code>occurance</code>
| <code>DateTimeField</code> (nullable)
| <code>datetime | None</code>
| When the request should take place. Spelled <code>occurance</code> in both model and spec — the typo is intentional, match it.
|}

=== Relationships ===

{| class="wikitable"
|-
! Field
! Model type
! Spec type
! Notes
|-
| <code>facility</code>
| <code>FK → facility.Facility</code>
| (not in write spec)
| Owning facility. <code>PROTECT</code>. Set server-side from request context.
|-
| <code>patient</code>
| <code>FK → emr.Patient</code>
| (derived)
| Subject of the request. <code>CASCADE</code>. Not accepted from clients — set server-side from <code>encounter.patient</code> on create.
|-
| <code>encounter</code>
| <code>FK → emr.Encounter</code> (nullable)
| <code>UUID4</code> (create only)
| Encounter the request was created in. <code>CASCADE</code>. Required as a UUID on <code>Create</code>; resolved via <code>get_object_or_404</code>. Read back as a serialized encounter dict.
|-
| <code>healthcare_service</code>
| <code>FK → emr.HealthcareService</code> (nullable)
| <code>UUID4 | None</code>
| Service fulfilling the request. <code>PROTECT</code>. Write accepts <code>external_id</code>; resolved server-side. Excluded from base serialize; returned only on <code>Retrieve</code>.
|-
| <code>activity_definition</code>
| <code>FK → emr.ActivityDefinition</code> (nullable)
| (read only)
| Template the request was created from. <code>PROTECT</code>. Serialized only on <code>Retrieve</code>.
|-
| <code>requester</code>
| <code>FK → users.User</code> (nullable)
| <code>UUID4 | None</code> (write) / <code>dict | None</code> (read)
| User who placed the request. <code>CASCADE</code>. Write accepts <code>external_id</code>; read returns a cached <code>UserSpec</code> dict.
|-
| <code>locations</code>
| <code>ArrayField[int]</code>
| <code>list[UUID4]</code> (write) / <code>list[dict]</code> (read)
| Facility-location IDs the request applies to. Model default <code>[]</code>. Write accepts location <code>external_id</code>s, stored on <code>obj._locations</code> for the manager to persist; serialized as <code>FacilityLocationListSpec</code> dicts only on <code>Retrieve</code>.
|-
| <code>tags</code>
| <code>ArrayField[int]</code>
| <code>list[dict]</code> (read)
| Tag IDs. Model default <code>[]</code>. Rendered via <code>SingleFacilityTagManager().render_tags(obj)</code> on read; not set directly from the write spec.
|}

== Enums ==

=== Status values ===

<code>ServiceRequestStatusChoices</code> values are snake_case, not the hyphenated FHIR codes.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>draft</code>
| Request is being drafted, not yet actionable
|-
| <code>active</code>
| Request is active
|-
| <code>on_hold</code>
| Request is paused
|-
| <code>entered_in_error</code>
| Request was entered in error
|-
| <code>ended</code>
| Request has ended
|-
| <code>completed</code>
| Request has been fulfilled
|-
| <code>revoked</code>
| Request was revoked/cancelled
|}

<code>spec.py</code> derives two groupings from these:

* <code>SERVICE_REQUEST_COMPLETED_CHOICES</code> = <code>completed</code>, <code>revoked</code>, <code>ended</code>, <code>entered_in_error</code> (terminal states).
* <code>SERVICE_REQUEST_CANCELLED_CHOICES</code> = <code>revoked</code>, <code>entered_in_error</code>.

There is no <code>unknown</code> status.

=== Intent values ===

<code>ServiceRequestIntentChoices</code>

{| class="wikitable"
|-
! Value
|-
| <code>proposal</code>
|-
| <code>plan</code>
|-
| <code>directive</code>
|-
| <code>order</code>
|}

=== Priority values ===

<code>ServiceRequestPriorityChoices</code>

{| class="wikitable"
|-
! Value
|-
| <code>routine</code>
|-
| <code>urgent</code>
|-
| <code>asap</code>
|-
| <code>stat</code>
|}

=== Category values ===

<code>category</code> reuses <code>ActivityDefinitionCategoryOptions</code> from <code>care/emr/resources/activity_definition/spec.py</code>.

{| class="wikitable"
|-
! Value
|-
| <code>laboratory</code>
|-
| <code>imaging</code>
|-
| <code>counselling</code>
|-
| <code>surgical_procedure</code>
|-
| <code>education</code>
|}

== Bound value sets ==

Each coded <code>Coding</code> field validates its <code>code</code> against a registered Care value set (<code>ValueSetBoundCoding[...]</code>).

{| class="wikitable"
|-
! Field
! Value set slug
! Composition
|-
| <code>code</code>
| <code>activity-definition-procedure-code</code>
| SNOMED CT <code>is-a 71388002</code> (Procedure). See [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/activity_definition/valueset.py <code>activity_definition/valueset.py</code>].
|-
| <code>body_site</code>
| <code>system-body-site-observation</code>
| SNOMED CT — explicit limb/joint concepts plus <code>is-a 442083009</code>. See [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/observation/valueset.py <code>observation/valueset.py</code>].
|}

== Resource specs (API schema) ==

Every spec subclasses <code>EMRResource</code> (<code>serialize</code> / <code>de_serialize</code>, with <code>perform_extra_serialization</code> / <code>perform_extra_deserialization</code> hooks — see [[References/Base models & conventions|Base model]]). The base sets <code>__model__ = ServiceRequest</code> and <code>__exclude__ = ["encounter", "healthcare_service", "locations"]</code>, so those three fields are handled only by the explicit per-spec hooks.

{| class="wikitable"
|-
! Spec class
! Role
! Adds / overrides
|-
| <code>BaseServiceRequestSpec</code>
| shared
| <code>id</code>, <code>title</code>, <code>status</code>, <code>intent</code>, <code>priority</code>, <code>category</code>, <code>do_not_perform</code>, <code>note</code>, <code>code</code> (required), <code>body_site</code>, <code>occurance</code>, <code>patient_instruction</code>
|-
| <code>ServiceRequestWriteSpec</code>
| write · shared
| Adds <code>healthcare_service: UUID4?</code>, <code>locations: list[UUID4]</code>, <code>requester: UUID4?</code>. Resolves <code>healthcare_service</code> and <code>requester</code> from <code>external_id</code>; stashes <code>locations</code> on <code>obj._locations</code>.
|-
| <code>ServiceRequestCreateSpec</code>
| write · create
| Adds required <code>encounter: UUID4</code>. Resolves the encounter and sets <code>obj.patient = obj.encounter.patient</code> server-side.
|-
| <code>ServiceRequestUpdateSpec</code>
| write · update
| Makes <code>title</code>, <code>status</code>, <code>intent</code>, <code>priority</code>, <code>category</code>, <code>code</code> all optional for partial update.
|-
| <code>ServiceRequestReadSpec</code>
| read · list
| Adds <code>created_date</code>, <code>modified_date</code>, <code>encounter</code> (serialized via <code>EncounterListSpec</code>), <code>tags</code> (rendered), <code>requester</code> (cached <code>UserSpec</code>). Sets <code>id = external_id</code>.
|-
| <code>ServiceRequestRetrieveSpec</code>
| read · detail
| Extends Read with <code>locations</code> (<code>FacilityLocationListSpec</code>), <code>healthcare_service</code> (<code>HealthcareServiceReadSpec</code>), <code>activity_definition</code> (<code>ActivityDefinitionReadSpec</code>), <code>specimens</code> (<code>SpecimenReadSpec</code>), <code>diagnostic_reports</code> (<code>DiagnosticReportListSpec</code>), embedded <code>encounter.patient</code> (<code>PatientRetrieveSpec</code>), and audit <code>created_by</code>/<code>updated_by</code>.
|}

=== Write-side behaviour (<code>perform_extra_deserialization</code>) ===

* <code>healthcare_service</code>, when provided, is looked up by <code>external_id</code> and assigned.
* <code>requester</code>, when provided, is looked up by <code>external_id</code> via <code>get_object_or_404(User, ...)</code>.
* <code>locations</code>: the list of UUIDs is stored on <code>obj._locations</code>; the persisting view/manager translates them to integer IDs for the <code>locations</code> array.
* On create only, <code>encounter</code> is required, fetched via <code>get_object_or_404(Encounter, ...)</code>, and <code>obj.patient</code> is forced to <code>encounter.patient</code>. Clients cannot set <code>patient</code> directly.

=== Read-side behaviour (<code>perform_extra_serialization</code>) ===

* <code>id</code> is set to <code>external_id</code>; <code>encounter</code> is serialized with <code>EncounterListSpec</code>; <code>tags</code> come from <code>SingleFacilityTagManager().render_tags(obj)</code>; <code>requester</code>, if set, is a cached <code>UserSpec</code>.
* On retrieve only: queries <code>FacilityLocation</code> for <code>obj.locations</code>; serializes <code>healthcare_service</code> and <code>activity_definition</code> when present; fetches the related <code>Specimen</code> and <code>DiagnosticReport</code> rows that reference this request; embeds the patient (<code>PatientRetrieveSpec</code>, scoped to <code>obj.facility</code>) under <code>encounter.patient</code>; and attaches audit users.

== Methods & save behaviour ==

* <code>ServiceRequest</code> inherits <code>save</code>, soft-delete, and audit behaviour from <code>EMRBaseModel</code> (see [[References/Base models & conventions|Base model]]). The model defines no custom <code>save</code> override.
* The Pydantic write specs enforce all write validation — enums, required <code>code</code>, bound value sets, encounter requirement — during <code>de_serialize</code>, not Django field choices. The DB columns are plain <code>CharField</code>/<code>JSONField</code>.
* <code>patient</code> is never accepted from the client; it is derived from <code>encounter.patient</code> on create.
* Related <code>Specimen</code> and <code>DiagnosticReport</code> records reference the request via their own <code>service_request</code> FK. The detail view (<code>Retrieve</code>) reads them back rather than storing them on the request.

== API integration notes ==

Things that trip up integrators:

* Spellings follow Care conventions, not FHIR: status/intent/priority are snake_case enum values, and <code>occurance</code> keeps its model typo.
* <code>code</code> is required and <code>body_site</code> optional; both are single <code>Coding</code> objects validated against their bound value sets — not <code>CodeableConcept</code>.
* <code>category</code>, <code>status</code>, <code>intent</code>, and <code>priority</code> are validated as enums by the spec even though the columns are free <code>CharField</code>s.
* Write <code>healthcare_service</code>, <code>requester</code>, and <code>locations</code> as <code>external_id</code>/UUIDs and let the server resolve them. <code>encounter</code> (UUID) is required on create and determines the patient.
* <code>locations</code> and <code>tags</code> store ID arrays for fast filtering — drive them through the location/tag managers rather than setting the raw arrays from clients.

== Related models ==

* [[References/Activity Definition]] — template a request can be created from; supplies the <code>category</code> enum and <code>code</code> value set
* [[References/Encounter]] — required context on create; supplies the patient
* [[References/Patient]] — subject, derived from the encounter
* [[References/Specimen]] — specimens collected for a request
* [[References/Diagnostic Report]] — reports produced for a request
* [[References/Observation]] — shares the body-site value set
* [[References/Healthcare Service]] — service fulfilling the request
* [[References/Location]] — facility locations the request applies to
* [[References/User & Skills|User]] — requester / audit users

{{Related}}

References/Service Request - Revision history

Admin: Automated edit (via update-page on MediaWiki MCP Server)

Admin: OHC identity seed