Facility administration

Location

FacilityLocation 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…

3.1 · versioned documentation · 9 min read

FacilityLocation 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: care/emr/models/location.py
• Resource spec: care/emr/resources/location/spec.py
• Base resource: care/emr/resources/base.py
• Coding type: care/emr/resources/common/coding.py

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 FHIR Location resource.

The Django model is only the storage layer. location_type, metadata, and cached_parent_json are opaque JSONFields; their real shape lives in the Pydantic resource specs (care/emr/resources/location/spec.py), which also define every enum and the read/write schema split. See Resource specs (API schema).

Models

All three extend EMRBaseModel, which supplies external_id, audit fields, and soft-delete semantics.

FacilityLocation fields

Descriptive

Hierarchy & tree caches

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

Access & encounter

Enum values

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

StatusChoices values

FacilityLocationOperationalStatusChoices values

FHIR HL7 v2 bed/location operational status codes.

FacilityLocationModeChoices values

FacilityLocationFormChoices values

FHIR location-physical-type codes.

LocationEncounterAvailabilityStatusChoices values

Used by FacilityLocationEncounter.status — how an encounter occupies a location.

LocationAvailabilityStatusChoices values

The server-derived values that system_availability_status resolves to.

Coding shape

location_type is a single Coding object (extra="forbid"):

Coding {
  system:  str | None = None
  version: str | None = None
  code:    str            # required
  display: str | None = None
}

Related models

FacilityLocationOrganization

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.

location     → FK FacilityLocation (CASCADE)
organization → FK FacilityOrganization (CASCADE)

Saving one of these rows calls location.save() (rebuilding facility_organization_cache), then location.cascade_changes() to propagate the grant down to descendants asynchronously. On write, the organization set comes from FacilityLocationWriteSpec.organizations, a list of UUIDs.

FacilityLocationEncounter

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

FacilityLocation.current_encounter is populated from these rows.

Methods & save behaviour

save() side effects

On insert (no id yet):

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

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

Caches & cascade

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

validate_uniqueness()

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

Resource specs (API schema)

The Pydantic specs in care/emr/resources/location/spec.py define the request/response shapes. All extend EMRResource, which provides serialize/de_serialize plus the perform_extra_serialization/perform_extra_deserialization hooks (see base model and base.py).

Location specs

Encounter-association specs

Server-maintained behaviour

• These are platform-maintained — don't write them from a client: system_availability_status, has_children, level_cache, parent_cache, cached_parent_json, facility_organization_cache, current_encounter, and sort_index (when left unset).
• On read, parent comes back as the serialized parent chain (get_parent_json()), never the raw FK.
• Access granted through organizations / FacilityLocationOrganization lands asynchronously; the org cache and descendant caches settle only after the cascade task runs.
• location_type takes a free Coding (no value-set slug) and metadata 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 Location resource, so payload field names may differ from these Django names.
• mode separates kind (a location type) from instance (a concrete location such as a bed). Beds are FacilityLocation instances, not a separate model, and instance locations cannot have children.
• parent, organizations, and mode are settable only at creation (FacilityLocationWriteSpec). Updates go through FacilityLocationUpdateSpec, which omits all three.
• For fields you can't write, see Server-maintained behaviour.

Related

• Reference: Facility
• Reference: Organization
• Reference: Encounter
• Reference: Base model
• Source: location.py on GitHub
• Source: location/spec.py on GitHub

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/facility/location.mdx:1 · f6e9f05f