Laboratory & radiology

Service Request

A ServiceRequest is an order or proposal to perform an action — clinical or otherwise — for a patient . It drives the creation of specimens, diagnostic reports, observations, and procedures, each of which links back to the originating request.…

3.1 · versioned documentation · 8 min read

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

Source:

• Model: care/emr/models/service_request.py
• Resource spec: care/emr/resources/service_request/spec.py

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

Models

ServiceRequest extends EMRBaseModel, the shared MANSOQ EMR base that supplies external_id, audit fields created_by/updated_by, created_date/modified_date, meta, and soft-delete semantics — see Base model.

ServiceRequest fields

Request definition

A bound Coding (ValueSetBoundCoding) has the shape:

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

Clinical detail

Relationships

Enums

Status values

ServiceRequestStatusChoices values are snake_case, not the hyphenated FHIR codes.

spec.py derives two groupings from these:

• SERVICE_REQUEST_COMPLETED_CHOICES = completed, revoked, ended, entered_in_error (terminal states).
• SERVICE_REQUEST_CANCELLED_CHOICES = revoked, entered_in_error.

There is no unknown status.

Intent values

ServiceRequestIntentChoices

Priority values

ServiceRequestPriorityChoices

Category values

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

Bound value sets

Each coded Coding field validates its code against a registered MANSOQ value set (ValueSetBoundCoding[...]).

Resource specs (API schema)

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

Write-side behaviour (perform_extra_deserialization)

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

Read-side behaviour (perform_extra_serialization)

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

Methods & save behaviour

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

API integration notes

Things that trip up integrators:

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

Related models

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

Source evidence

References are pinned to the private MANSOQ source repository. Repository access is required to open these links.

• repositories/platform/mansoq-documentation/versioned_docs/version-3.1/references/clinical/service-request.mdx:1 · f6e9f05f