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

2026-07-06T04:05:26Z

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

← Older revision		Revision as of 09:35, 6 July 2026
Line 250:		Line 250:
	* On write, <code>locations</code> and <code>managing_organization</code> are <code>external_id</code>s (UUIDs); detail responses embed the full objects. Nothing at the DB level confirms the referenced locations belong to the same <code>facility</code>.		* On write, <code>locations</code> and <code>managing_organization</code> are <code>external_id</code>s (UUIDs); detail responses embed the full objects. Nothing at the DB level confirms the referenced locations belong to the same <code>facility</code>.
	* <code>facility</code> is never accepted in the request body — it's set from the URL context.		* <code>facility</code> is never accepted in the request body — it's set from the URL context.

			{{Navbox facility}}

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

Admin: OHC identity seed

2026-07-04T22:45:07Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=facility
|title=Healthcare Service
|order=6
|introduced=3.0
|model=HealthcareService
|reference=References/Base models & conventions
}}

A <code>HealthcareService</code> is a service a facility offers — cardiology, lab, radiology, pharmacy — scoped to one or more locations and to the facility organization that manages it. You touch it when modeling what a facility provides and where.

The Django model is thin storage: <code>service_type</code> and <code>styling_metadata</code> are opaque <code>JSONField</code>s. Their real structure lives in the Pydantic resource specs, which also define the bound value set, the <code>internal_type</code> enum, and the separate read and write API schemas.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/healthcare_service.py <code>care/emr/models/healthcare_service.py</code>]
* Spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/healthcare_service/spec.py <code>care/emr/resources/healthcare_service/spec.py</code>]
* Value set: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/healthcare_service/valueset.py <code>care/emr/resources/healthcare_service/valueset.py</code>]

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>HealthcareService</code>
| A service a facility offers (e.g. cardiology, lab, radiology), scoped to locations and a managing organization
|}

<code>HealthcareService</code> extends [[References/Base models & conventions|<code>EMRBaseModel</code>]], the shared Care EMR base that provides <code>external_id</code>, audit fields, soft-delete via <code>deleted</code>, <code>created_by</code>/<code>updated_by</code>, and <code>history</code>/<code>meta</code> JSON.

== <code>HealthcareService</code> fields ==

=== Identity & classification ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=HealthcareService|section=Identity & classification|name=name|type=CharField(1024)|notes=Display name. Required on write; no default}}
{{Field|model=HealthcareService|section=Identity & classification|name=service_type|type=JSONField → Coding|notes=Holds one FHIR-style <code>Coding</code> object, not a string. Defaults to <code>{}</code>. In the API it is a <code>ValueSetBoundCoding</code> bound to the '''Healthcare Service Type Code''' value set (below). Optional (<code>None</code>)}}
{{Field|model=HealthcareService|section=Identity & classification|name=internal_type|type=CharField(255)|notes=Nullable, default <code>None</code>. The API constrains it to the <code>HealthcareServiceInternalType</code> enum (<code>pharmacy</code> / <code>lab</code> / <code>scheduling</code> / <code>store</code>); the column does not}}
{{Field|model=HealthcareService|section=Identity & classification|name=extra_details|type=TextField|notes=Free text. Not nullable and no DB default, so write specs require a value — an empty string counts}}
|}

=== Scope & placement ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=HealthcareService|section=Scope & placement|name=facility|type=FK → facility.Facility|notes=<code>PROTECT</code>; nullable (<code>default=None</code>, <code>blank=True</code>). Excluded from every spec (<code>__exclude__ = ["facility"]</code>) and set server-side from the URL context — never from the request body}}
{{Field|model=HealthcareService|section=Scope & placement|name=locations|type=ArrayField[int]|notes=Defaults to <code>[]</code>. Holds <code>FacilityLocation</code> '''primary-key integers''', not FK rows. Write specs take location <code>external_id</code>s (UUIDs); retrieve specs return serialized location objects}}
{{Field|model=HealthcareService|section=Scope & placement|name=managing_organization|type=FK → emr.FacilityOrganization|notes=<code>PROTECT</code>; nullable. The facility-scoped org (department/team) responsible for the service. Write specs take its <code>external_id</code> (UUID), resolved server-side}}
|}

=== Presentation ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=HealthcareService|section=Presentation|name=styling_metadata|type=JSONField → dict|notes=Nullable in the DB; defaults to <code>{}</code> in the specs. An open JSON bag of UI hints (colors, icons) with no backend semantics}}
|}

== Coded field shapes (JSON fields) ==

=== <code>service_type</code> → <code>Coding</code> ===

<code>service_type</code> stores a single <code>Coding</code> object. In the API it is a <code>ValueSetBoundCoding</code> whose <code>code</code> is checked against the '''Healthcare Service Type Code''' value set during de-serialization. Optional (<code>None</code>).

<syntaxhighlight lang="text">Coding {
system: str | None # e.g. "http://terminology.hl7.org/CodeSystem/service-type"
version: str | None
code: str # required; validated against the bound value set
display: str | None
}
# extra="forbid" — unknown keys rejected</syntaxhighlight>
=== Bound value set — Healthcare Service Type Code ===

{| class="wikitable"
|-
! Property
! Value
|-
| Name
| <code>Healthcare Service Type Code</code>
|-
| Slug
| <code>healthcare-service-type-code</code>
|-
| Status
| <code>active</code>
|-
| Compose / include system
| <code>http://terminology.hl7.org/CodeSystem/service-type</code>
|-
| System version
| <code>2.0.0</code>
|}

Registered via <code>register_valueset(...)</code> and <code>register_as_system()</code>. The <code>service_type.code</code> on create or update must resolve within this value set.

== Enums ==

=== <code>HealthcareServiceInternalType</code> values ===

Constrains <code>internal_type</code> in the specs (<code>str</code> enum). The model column is a plain <code>CharField</code>, so legacy or other values may already exist in storage.

{| class="wikitable"
|-
! Value
|-
| <code>pharmacy</code>
|-
| <code>lab</code>
|-
| <code>scheduling</code>
|-
| <code>store</code>
|}

== Related models ==

=== <code>facility.Facility</code> ===

<syntaxhighlight lang="text">facility → FK Facility (PROTECT, nullable)</syntaxhighlight>
The facility offering the service. <code>PROTECT</code> blocks deleting a facility that still has healthcare services. Excluded from specs and set from the request context. See [[References/Facility]].

=== <code>emr.FacilityOrganization</code> ===

<syntaxhighlight lang="text">managing_organization → FK FacilityOrganization (PROTECT, nullable)</syntaxhighlight>
The facility-scoped organization (department/team) that owns the service. Write specs take its <code>external_id</code> (UUID); the retrieve spec embeds it, serialized via <code>FacilityOrganizationReadSpec</code>. See [[References/Organization]].

=== Locations ===

<code>locations</code> is an <code>ArrayField</code> of integer PKs, not a relational join — each entry references a <code>FacilityLocation</code> row by primary key, with resolution and validation handled in application code rather than by a database foreign key. Write specs take location <code>external_id</code>s (UUIDs); the retrieve spec embeds each location, serialized via <code>FacilityLocationListSpec</code>. See [[References/Location]].

== Resource specs (API schema) ==

Every spec extends <code>EMRResource</code> (<code>care/emr/resources/base.py</code>), which provides <code>serialize</code> (DB object → spec) and <code>de_serialize</code> (spec → DB object), plus the <code>perform_extra_serialization</code> / <code>perform_extra_deserialization</code> hooks. <code>__exclude__ = ["facility"]</code> keeps <code>facility</code> out of every payload.

{| class="wikitable"
|-
! Spec class
! Role
! Notes
|-
| <code>BaseHealthcareServiceSpec</code>
| shared base
| Fields: <code>id</code>, <code>service_type</code>, <code>internal_type</code>, <code>name</code>, <code>styling_metadata</code>, <code>extra_details</code>. <code>__model__ = HealthcareService</code>, <code>__exclude__ = ["facility"]</code>
|-
| <code>HealthcareServiceWriteSpec</code>
| write · create & update
| Base fields '''plus''' <code>locations: list[UUID4]</code> (default <code>[]</code>) and <code>managing_organization: UUID4 | None</code>. Resolves <code>managing_organization</code> from its <code>external_id</code> in <code>perform_extra_deserialization</code>
|-
| <code>HealthcareServiceReadSpec</code>
| read · list
| Base fields. <code>perform_extra_serialization</code> sets <code>id</code> to <code>obj.external_id</code>
|-
| <code>HealthcareServiceRetrieveSpec</code>
| read · detail
| Extends <code>ReadSpec</code>; overrides <code>locations: list[dict]</code> (each location serialized via <code>FacilityLocationListSpec</code>) and <code>managing_organization: dict | None</code> (serialized via <code>FacilityOrganizationReadSpec</code>)
|}

=== Field exposure by spec ===

{| class="wikitable"
|-
! Field
! Base
! Write
! Read (list)
! Retrieve (detail)
|-
| <code>id</code> (UUID4)
| ✓ (read-only)
| ✓
| ✓ (= <code>external_id</code>)
| ✓ (= <code>external_id</code>)
|-
| <code>name</code> (str, required)
| ✓
| ✓
| ✓
| ✓
|-
| <code>service_type</code> (bound <code>Coding</code>, optional)
| ✓
| ✓
| ✓
| ✓
|-
| <code>internal_type</code> (enum, optional)
| ✓
| ✓
| ✓
| ✓
|-
| <code>styling_metadata</code> (dict, default <code>{}</code>)
| ✓
| ✓
| ✓
| ✓
|-
| <code>extra_details</code> (str, required)
| ✓
| ✓
| ✓
| ✓
|-
| <code>locations</code>
| —
| <code>list[UUID4]</code> (write)
| —
| <code>list[dict]</code> (embedded)
|-
| <code>managing_organization</code>
| —
| <code>UUID4 | None</code> (write)
| —
| <code>dict | None</code> (embedded)
|}

=== Validation & server-side behaviour ===

* '''<code>service_type</code>''' — a <code>ValueSetBoundCoding</code>. De-serialization runs <code>validate_valueset</code> on <code>code</code> against the <code>healthcare-service-type-code</code> value set, and <code>extra="forbid"</code> on the underlying <code>Coding</code> rejects unknown keys.
* '''<code>managing_organization</code>''' (write) — <code>perform_extra_deserialization</code> resolves the UUID via <code>get_object_or_404(FacilityOrganization, external_id=...)</code> and assigns the FK; a falsy value sets <code>managing_organization = None</code>.
* '''<code>locations</code>''' (write) — submitted as UUIDs. The retrieve spec resolves each PK back to a <code>FacilityLocation</code> and serializes it, silently skipping any that fail to load (<code>try/except … pass</code>).
* '''<code>id</code> / <code>external_id</code>''' — never written from the body. <code>de_serialize</code> skips both; <code>serialize</code> / <code>perform_extra_serialization</code> populate <code>id</code> from <code>obj.external_id</code>.
* '''<code>facility</code>''' — excluded from all specs and assigned server-side, so it can't be set or changed through the API body.
* No <code>status</code> field, and therefore no server-maintained <code>status_history</code>.

== Methods & save behaviour ==

* Inherits <code>save()</code>, soft-delete (<code>deleted</code>), audit fields (<code>created_by</code>/<code>updated_by</code>), <code>history</code>/<code>meta</code>, and <code>external_id</code> from [[References/Base models & conventions|<code>EMRBaseModel</code>]].
* <code>EMRResource.serialize</code> / <code>de_serialize</code> drive read/write conversion; the extra (de)serialization hooks above handle FK resolution and embedded serialization.
* <code>facility</code> and <code>managing_organization</code> use <code>on_delete=PROTECT</code>, so deleting either while a service references it is blocked at the DB level.

== API integration notes ==

The API surface is built from the spec classes, not the raw model. Three things commonly trip up integrators:

* <code>service_type</code> takes a <code>Coding</code> object whose <code>code</code> is in the bound value set, not a bare string.
* On write, <code>locations</code> and <code>managing_organization</code> are <code>external_id</code>s (UUIDs); detail responses embed the full objects. Nothing at the DB level confirms the referenced locations belong to the same <code>facility</code>.
* <code>facility</code> is never accepted in the request body — it's set from the URL context.

{{Related}}

References/Healthcare Service - Revision history

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

Admin: OHC identity seed