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

2026-07-06T04:05:00Z

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

← Older revision		Revision as of 09:35, 6 July 2026
Line 395:		Line 395:
	* <code>parent</code>, <code>organizations</code>, and <code>mode</code> are settable only at creation (<code>FacilityLocationWriteSpec</code>). Updates go through <code>FacilityLocationUpdateSpec</code>, which omits all three.		* <code>parent</code>, <code>organizations</code>, and <code>mode</code> are settable only at creation (<code>FacilityLocationWriteSpec</code>). Updates go through <code>FacilityLocationUpdateSpec</code>, which omits all three.
	* For fields you can't write, see [[#server-maintained-behaviour\|Server-maintained behaviour]].		* For fields you can't write, see [[#server-maintained-behaviour\|Server-maintained behaviour]].

			{{Navbox facility}}

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

Admin: OHC identity seed

2026-07-04T22:45:10Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=facility
|title=Location
|order=5
|introduced=3.0
|model=Location
|reference=References/Base models & conventions
}}

<code>FacilityLocation</code> is a node in a facility's building/ward/room/bed tree — where resources sit and where care happens. You work with it when you place an encounter somewhere, scope organization access to part of a facility, or model a site's physical layout.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/location.py <code>care/emr/models/location.py</code>]
* Resource spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/location/spec.py <code>care/emr/resources/location/spec.py</code>]
* Base resource: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/base.py <code>care/emr/resources/base.py</code>]
* Coding type: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/common/coding.py <code>care/emr/resources/common/coding.py</code>]

Nodes nest without limit: every node may have a parent and children, so one tree can run from a campus down to a single bed. Encounters and organizations attach to nodes, and access granted at a node cascades to its descendants asynchronously rather than resolving on each request. The model maps to the [<nowiki/>https://build.fhir.org/location.html FHIR Location] resource.

The Django model is only the storage layer. <code>location_type</code>, <code>metadata</code>, and <code>cached_parent_json</code> are opaque <code>JSONField</code>s; their real shape lives in the Pydantic resource specs (<code>care/emr/resources/location/spec.py</code>), which also define every enum and the read/write schema split. See [[#resource-specs-api-schema|Resource specs (API schema)]].

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>FacilityLocation</code>
| A node in a facility's location tree (building, ward, room, bed, …)
|-
| <code>FacilityLocationOrganization</code>
| Grants a <code>FacilityOrganization</code> access to a location
|-
| <code>FacilityLocationEncounter</code>
| Records how/when an encounter occupied a location (e.g. a bed)
|}

All three extend [[References/Base models & conventions|<code>EMRBaseModel</code>]], which supplies <code>external_id</code>, audit fields, and soft-delete semantics.

== <code>FacilityLocation</code> fields ==

=== Descriptive ===

{| class="wikitable"
|-
! Field
! Type
! Spec values / shape
! Notes
{{Field|model=Location|section=Descriptive|name=name|type=CharField(255)|notes=<code>str</code>, required}}
{{Field|model=Location|section=Descriptive|name=description|type=CharField(255)|notes=<code>str</code>, required}}
{{Field|model=Location|section=Descriptive|name=status|type=CharField(255)|notes=<code>StatusChoices</code> enum}}
{{Field|model=Location|section=Descriptive|name=operational_status|type=CharField(255)|notes=<code>FacilityLocationOperationalStatusChoices</code> enum}}
{{Field|model=Location|section=Descriptive|name=system_availability_status|type=CharField(255)|notes=<code>str</code> (read-only)}}
{{Field|model=Location|section=Descriptive|name=mode|type=CharField(255)|notes=<code>FacilityLocationModeChoices</code> enum}}
{{Field|model=Location|section=Descriptive|name=location_type|type=JSONField (default=dict, nullable)|notes=<code>Coding | None</code> (default <code>None</code>)}}
{{Field|model=Location|section=Descriptive|name=form|type=CharField(255)|notes=<code>FacilityLocationFormChoices</code> enum}}
|}

=== Hierarchy & tree caches ===

These fields denormalize the tree so descendants are queryable without recursive joins. <code>save()</code> and the cascade task own them; never set them from a client.

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Location|section=Hierarchy & tree caches|name=parent|type=FK → FacilityLocation|notes=<code>SET_NULL</code>, nullable. Immediate parent. Accepted on write as a UUID (<code>parent</code>); on read it's dropped in favour of the serialized parent JSON}}
{{Field|model=Location|section=Hierarchy & tree caches|name=root_location|type=FK → self|notes=<code>CASCADE</code>, <code>related_name="root"</code>, nullable. Top of this node's tree. Excluded from specs}}
{{Field|model=Location|section=Hierarchy & tree caches|name=has_children|type=BooleanField|notes=<code>default=False</code>. Set <code>True</code> on the parent when a child is created. Read-only in list/retrieve specs}}
{{Field|model=Location|section=Hierarchy & tree caches|name=level_cache|type=IntegerField|notes=<code>default=0</code>. Depth in the tree (<code>parent.level_cache + 1</code>)}}
{{Field|model=Location|section=Hierarchy & tree caches|name=parent_cache|type=ArrayField[int]|notes=Ordered ancestor IDs (<code>parent.parent_cache + [parent.id]</code>)}}
{{Field|model=Location|section=Hierarchy & tree caches|name=cached_parent_json|type=JSONField (default=dict)|notes=Serialized parent chain (<code>FacilityLocationListSpec</code>) plus a <code>cache_expiry</code> ISO timestamp. Rebuilt lazily by <code>get_parent_json()</code>, invalidated by the cascade task. <code>cache_expiry_days = 15</code>}}
{{Field|model=Location|section=Hierarchy & tree caches|name=sort_index|type=IntegerField|notes=<code>default=0</code>. In specs <code>int | None</code>, default <code>0</code>, constrained <code>0 ≤ sort_index ≤ 10000</code> (<code>MIN_SORT_INDEX</code>/<code>MAX_SORT_INDEX</code>). Auto-assigned as <code>max(sibling sort_index) + 1</code> when left unset}}
|}

=== Access & encounter ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Location|section=Access & encounter|name=facility|type=FK → facility.Facility|notes=<code>PROTECT</code>. Owning facility. Excluded from specs — resolved from route/context}}
{{Field|model=Location|section=Access & encounter|name=facility_organization_cache|type=ArrayField[int]|notes=<code>default=list</code>. Org IDs that can reach this location; rebuilt by <code>sync_organization_cache()</code>}}
{{Field|model=Location|section=Access & encounter|name=current_encounter|type=FK → Encounter|notes=<code>SET_NULL</code>, nullable, <code>default=None</code>. Populated from <code>FacilityLocationEncounter</code>. Excluded from the base spec; surfaced as serialized JSON in list/retrieve specs}}
{{Field|model=Location|section=Access & encounter|name=metadata|type=JSONField|notes=<code>default=dict</code>. Open extension bag for deployment-specific data}}
|}

== Enum values ==

Every enum is a <code>str</code> <code>Enum</code> in <code>care/emr/resources/location/spec.py</code>. Values below are character-for-character from source.

=== <code>StatusChoices</code> values ===

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>active</code>
| Location is active
|-
| <code>inactive</code>
| Location is inactive
|-
| <code>unknown</code>
| Status unknown
|}

=== <code>FacilityLocationOperationalStatusChoices</code> values ===

FHIR HL7 v2 bed/location operational status codes.

{| class="wikitable"
|-
! Code
! Meaning
|-
| <code>C</code>
| Closed
|-
| <code>H</code>
| Housekeeping
|-
| <code>O</code>
| Occupied
|-
| <code>U</code>
| Unoccupied
|-
| <code>K</code>
| Contaminated
|-
| <code>I</code>
| Isolated
|}

=== <code>FacilityLocationModeChoices</code> values ===

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>instance</code>
| A single, concrete location (e.g. Bed 1). Instances cannot have children
|-
| <code>kind</code>
| A class/type of location (e.g. a ward or building)
|}

=== <code>FacilityLocationFormChoices</code> values ===

FHIR <code>location-physical-type</code> codes.

{| class="wikitable"
|-
! Code
! Meaning
|-
| <code>si</code>
| Site
|-
| <code>bu</code>
| Building
|-
| <code>wi</code>
| Wing
|-
| <code>wa</code>
| Ward
|-
| <code>lvl</code>
| Level
|-
| <code>co</code>
| Corridor
|-
| <code>ro</code>
| Room
|-
| <code>bd</code>
| Bed
|-
| <code>ve</code>
| Vehicle
|-
| <code>ho</code>
| House
|-
| <code>ca</code>
| Cabinet
|-
| <code>rd</code>
| Road
|-
| <code>area</code>
| Area
|-
| <code>jdn</code>
| Jurisdiction
|-
| <code>vi</code>
| Virtual
|}

=== <code>LocationEncounterAvailabilityStatusChoices</code> values ===

Used by <code>FacilityLocationEncounter.status</code> — how an encounter occupies a location.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>planned</code>
| Occupancy planned
|-
| <code>active</code>
| Currently occupied
|-
| <code>reserved</code>
| Reserved
|-
| <code>completed</code>
| Occupancy ended
|}

=== <code>LocationAvailabilityStatusChoices</code> values ===

The server-derived values that <code>system_availability_status</code> resolves to.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>available</code>
| Not actively tied to an encounter
|-
| <code>reserved</code>
| Tied to an encounter
|}

=== <code>Coding</code> shape ===

<code>location_type</code> is a single <code>Coding</code> object (<code>extra="forbid"</code>):

<syntaxhighlight lang="text">Coding {
system: str | None = None
version: str | None = None
code: str # required
display: str | None = None
}</syntaxhighlight>
== Related models ==

=== <code>FacilityLocationOrganization</code> ===

Links an organization to a location. Users under that organization inherit access to the location and its encounters through whatever role they hold on the organization.

<syntaxhighlight lang="text">location → FK FacilityLocation (CASCADE)
organization → FK FacilityOrganization (CASCADE)</syntaxhighlight>
Saving one of these rows calls <code>location.save()</code> (rebuilding <code>facility_organization_cache</code>), then <code>location.cascade_changes()</code> to propagate the grant down to descendants asynchronously. On write, the organization set comes from <code>FacilityLocationWriteSpec.organizations</code>, a list of UUIDs.

=== <code>FacilityLocationEncounter</code> ===

A bed assignment, in effect: it records how an encounter occupied a location over a time window.

{| class="wikitable"
|-
! Field
! Type
! Spec
! Notes
{{Field|model=Location|section=FacilityLocationEncounter|name=status|type=CharField(25)|notes=<code>LocationEncounterAvailabilityStatusChoices</code>}}
{{Field|model=Location|section=FacilityLocationEncounter|name=location|type=FK → FacilityLocation|notes=excluded / nested}}
{{Field|model=Location|section=FacilityLocationEncounter|name=encounter|type=FK → Encounter|notes=UUID on write, JSON on read}}
{{Field|model=Location|section=FacilityLocationEncounter|name=start_datetime|type=DateTimeField|notes=<code>datetime</code> (required)}}
{{Field|model=Location|section=FacilityLocationEncounter|name=end_datetime|type=DateTimeField (nullable)|notes=<code>datetime | None</code>}}
|}

<code>FacilityLocation.current_encounter</code> is populated from these rows.

== Methods & save behaviour ==

=== <code>save()</code> side effects ===

On insert (no <code>id</code> yet):

# If <code>parent</code> is set, <code>level_cache</code>, <code>root_location</code>, and <code>parent_cache</code> are derived from the parent, and the parent's <code>has_children</code> is flipped to <code>True</code> if needed.
# If <code>sort_index</code> is unset, it's assigned <code>max(sibling sort_index) + 1</code>.

On update, <code>cached_parent_json</code> is cleared so it rebuilds lazily. After every <code>super().save()</code>, <code>sync_organization_cache()</code> runs and persists <code>facility_organization_cache</code> through a second <code>save(update_fields=[...])</code>, so each write touches the row twice.

=== Caches & cascade ===

* <code>sync_organization_cache()</code> — unions the parent's org cache, the org chains of every linked <code>FacilityLocationOrganization</code>, and the facility's <code>default_internal_organization_id</code>, then writes <code>facility_organization_cache</code>.
* <code>get_parent_json()</code> — returns the cached parent chain, refreshing <code>cached_parent_json</code> (via <code>FacilityLocationListSpec.serialize(parent)</code>) once it expires (<code>cache_expiry_days = 15</code>).
* <code>cascade_changes()</code> / <code>handle_cascade(base_location)</code> — a Celery task that walks every descendant and re-saves it to invalidate each node's <code>cached_parent_json</code>. It fires when a location's organizations change, so propagation is eventually consistent, not immediate.

=== <code>validate_uniqueness()</code> ===

Classmethod that enforces <code>name</code> uniqueness among siblings at the same <code>level_cache</code> within the same <code>root_location</code> — or among root-level locations when there's no root. For a new instance with a <code>parent</code>, <code>level_cache</code> and <code>root_location</code> are computed from that parent before the check runs.

== Resource specs (API schema) ==

The Pydantic specs in <code>care/emr/resources/location/spec.py</code> define the request/response shapes. All extend <code>EMRResource</code>, which provides <code>serialize</code>/<code>de_serialize</code> plus the <code>perform_extra_serialization</code>/<code>perform_extra_deserialization</code> hooks (see [[References/Base models & conventions|base model]] and [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/base.py <code>base.py</code>]).

=== Location specs ===

{| class="wikitable"
|-
! Spec class
! Role
! Exposes / notes
|-
| <code>FacilityLocationBaseSpec</code>
| shared base
| <code>__model__ = FacilityLocation</code>; <code>id: UUID4 | None</code>. <code>__exclude__ = [parent, facility, organizations, root_location, current_encounter]</code>
|-
| <code>FacilityLocationSpec</code>
| shared fields
| <code>status</code>, <code>operational_status</code>, <code>name</code>, <code>description</code>, <code>location_type</code> (<code>Coding | None</code>), <code>form</code>, <code>sort_index</code> (<code>0..10000</code>, default <code>0</code>)
|-
| <code>FacilityLocationWriteSpec</code>
| write · create
| Adds <code>parent: UUID4 | None</code>, <code>organizations: list[UUID4]</code> (required), <code>mode: FacilityLocationModeChoices</code>. Validator: a set <code>parent</code> must exist and must not be <code>mode = instance</code> ("Instances cannot have children"). <code>perform_extra_deserialization</code> resolves the <code>parent</code> UUID to an FK
|-
| <code>FacilityLocationUpdateSpec</code>
| write · update
| Same fields as <code>FacilityLocationSpec</code>. Drops <code>parent</code>/<code>organizations</code>/<code>mode</code> — hierarchy and mode are fixed after creation
|-
| <code>FacilityLocationMinimalListSpec</code>
| read · minimal
| Adds <code>parent: dict</code>, <code>mode: str</code>, <code>has_children: bool</code>, <code>system_availability_status: str</code>. <code>perform_extra_serialization</code> sets <code>id = external_id</code> and <code>parent = obj.get_parent_json()</code>
|-
| <code>FacilityLocationListSpec</code>
| read · list
| Extends minimal; adds <code>current_encounter: dict | None</code>, serialized via <code>EncounterListSpec</code> when present
|-
| <code>FacilityLocationRetrieveSpec</code>
| read · detail
| Extends list; adds <code>created_by</code>/<code>updated_by</code> (via <code>serialize_audit_users</code>)
|}

=== Encounter-association specs ===

{| class="wikitable"
|-
! Spec class
! Role
! Exposes / notes
|-
| <code>FacilityLocationEncounterBaseSpec</code>
| shared base
| <code>__model__ = FacilityLocationEncounter</code>; <code>id: UUID4 | None</code>. <code>__exclude__ = [encounter, location]</code>
|-
| <code>FacilityLocationEncounterCreateSpec</code>
| write · create
| <code>status</code> (<code>LocationEncounterAvailabilityStatusChoices</code>), <code>encounter: UUID4</code>, <code>start_datetime</code>, <code>end_datetime: datetime | None</code>. Validator: encounter must exist. <code>perform_extra_deserialization</code> resolves the <code>encounter</code> UUID to an FK
|-
| <code>FacilityLocationEncounterUpdateSpec</code>
| write · update
| <code>status</code>, <code>start_datetime</code>, <code>end_datetime</code>. Encounter is not re-assignable
|-
| <code>FacilityLocationEncounterListSpec</code>
| read · list
| <code>encounter: UUID4</code>, <code>start_datetime</code>, <code>end_datetime</code>, <code>status: str</code>; <code>id = external_id</code>
|-
| <code>FacilityLocationEncounterListSpecWithLocation</code>
| read · list
| Extends list; adds <code>location: dict</code> (serialized via <code>FacilityLocationListSpec</code>)
|-
| <code>FacilityLocationEncounterReadSpec</code>
| read · detail
| <code>encounter: dict</code> (serialized via <code>EncounterRetrieveSpec</code>), <code>start_datetime</code>, <code>end_datetime</code>, <code>status</code>, <code>created_by</code>/<code>updated_by</code>
|}

=== Server-maintained behaviour ===

* These are platform-maintained — don't write them from a client: <code>system_availability_status</code>, <code>has_children</code>, <code>level_cache</code>, <code>parent_cache</code>, <code>cached_parent_json</code>, <code>facility_organization_cache</code>, <code>current_encounter</code>, and <code>sort_index</code> (when left unset).
* On read, <code>parent</code> comes back as the serialized parent chain (<code>get_parent_json()</code>), never the raw FK.
* Access granted through <code>organizations</code> / <code>FacilityLocationOrganization</code> lands asynchronously; the org cache and descendant caches settle only after the cascade task runs.
* <code>location_type</code> takes a free <code>Coding</code> (no value-set slug) and <code>metadata</code> is an open bag, so both add coded or extension data without a schema migration.

== API integration notes ==

* The API is modelled on the FHIR <code>Location</code> resource, so payload field names may differ from these Django names.
* <code>mode</code> separates <code>kind</code> (a location type) from <code>instance</code> (a concrete location such as a bed). Beds are <code>FacilityLocation</code> instances, not a separate model, and <code>instance</code> locations cannot have children.
* <code>parent</code>, <code>organizations</code>, and <code>mode</code> are settable only at creation (<code>FacilityLocationWriteSpec</code>). Updates go through <code>FacilityLocationUpdateSpec</code>, which omits all three.
* For fields you can't write, see [[#server-maintained-behaviour|Server-maintained behaviour]].

{{Related}}

References/Location - Revision history

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

Admin: OHC identity seed