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

2026-07-06T04:01:40Z

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

← Older revision		Revision as of 09:31, 6 July 2026
Line 441:		Line 441:
	* <code>current_location</code> is a cached convenience field. The authoritative record is <code>location_history</code>, from <code>FacilityLocationEncounter</code>.		* <code>current_location</code> is a cached convenience field. The authoritative record is <code>location_history</code>, from <code>FacilityLocationEncounter</code>.
	* <code>extensions</code> holds custom key-value data without a schema migration, validated by <code>ExtensionValidator</code>.		* <code>extensions</code> holds custom key-value data without a schema migration, validated by <code>ExtensionValidator</code>.

			{{Navbox clinical}}

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

Admin: OHC identity seed

2026-07-04T22:44:22Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=clinical
|title=Encounter
|order=2
|introduced=3.0
|fhir=Encounter
|model=Encounter
|concept=Concepts/Patient
|reference=References/User & Skills
}}

An <code>Encounter</code> records a single interaction between a patient and a facility — a visit, admission, or consultation — and maps to the FHIR <code>Encounter</code> resource. You create one when a patient presents, drive it through its status lifecycle, and read it back to render the clinical timeline.

The Django model is only the storage layer: several fields are opaque <code>JSONField</code>s whose real shape lives in the Pydantic resource specs, so the model alone won't tell you what a write must look like. The spec tables below carry that detail.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/encounter.py <code>care/emr/models/encounter.py</code>]
* Specs: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/encounter/spec.py <code>care/emr/resources/encounter/spec.py</code>] · [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/encounter/constants.py <code>constants.py</code>] · [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/encounter/valueset.py <code>valueset.py</code>] · [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/encounter/enum_display_names.py <code>enum_display_names.py</code>]

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>Encounter</code>
| A single interaction between a patient and a facility (visit, admission, consultation)
|-
| <code>EncounterOrganization</code>
| Links an <code>Encounter</code> to a <code>FacilityOrganization</code> for access control
|}

Both extend [[References/Base models & conventions|<code>EMRBaseModel</code>]], the shared Care EMR base that provides <code>external_id</code>, audit fields, and soft-delete semantics.

== <code>Encounter</code> fields ==

=== Classification & status ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Encounter|section=Classification & status|name=status|type=CharField(100)|notes=Nullable in DB; '''required''' in API. One of <code>StatusChoices</code> (see below)}}
{{Field|model=Encounter|section=Classification & status|name=status_history|type=JSONField|notes=Default <code>{}</code>. Server-maintained. Shape: <code>{ "history": [{ "status": str, "moved_at": str (ISO datetime) }] }</code>}}
{{Field|model=Encounter|section=Classification & status|name=encounter_class|type=CharField(100)|notes=Nullable in DB; '''required''' in API. One of <code>ClassChoices</code> (see below)}}
{{Field|model=Encounter|section=Classification & status|name=encounter_class_history|type=JSONField|notes=Default <code>{}</code>. Server-maintained. Shape: <code>{ "history": [{ "status": str, "moved_at": str (ISO datetime) }] }</code>}}
{{Field|model=Encounter|section=Classification & status|name=priority|type=CharField(100)|notes=Nullable in DB; '''required''' in API. One of <code>EncounterPriorityChoices</code> (see below)}}
{{Field|model=Encounter|section=Classification & status|name=external_identifier|type=CharField(100)|notes=Nullable. Identifier from an external/source system}}
|}

=== Subject & facility ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Encounter|section=Subject & facility|name=patient|type=FK → Patient|notes=<code>CASCADE</code>. The patient this encounter is for. Set on create only}}
{{Field|model=Encounter|section=Subject & facility|name=facility|type=FK → Facility|notes=<code>PROTECT</code>. The facility where the encounter takes place. Set on create only}}
{{Field|model=Encounter|section=Subject & facility|name=appointment|type=FK → TokenBooking|notes=<code>SET_NULL</code>, nullable. Originating [[References/Booking}}
{{Field|model=Encounter|section=Subject & facility|name=current_location|type=FK → FacilityLocation|notes=<code>SET_NULL</code>, nullable. Cached current [[References/Location}}
|}

=== Timing & disposition ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Encounter|section=Timing & disposition|name=period|type=JSONField|notes=Default <code>{}</code>. <code>PeriodSpec { start: datetime (tz-aware, optional), end: datetime (tz-aware, optional) }</code>. If both set, <code>start ≤ end</code>}}
{{Field|model=Encounter|section=Timing & disposition|name=hospitalization|type=JSONField|notes=Default <code>{}</code>. <code>HospitalizationSpec</code> (see shape below). Nullable}}
{{Field|model=Encounter|section=Timing & disposition|name=discharge_summary_advice|type=TextField|notes=Nullable. Free-text discharge advice. Explicitly cleared to <code>None</code> on update when omitted}}
|}

=== Care team ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Encounter|section=Care team|name=care_team|type=JSONField|notes=Default <code>{}</code>. Stored as a list of <code>{ "user_id": int, "role": Coding }</code> entries. '''Not''' writable on create/update (excluded); managed via the dedicated care-team write spec}}
{{Field|model=Encounter|section=Care team|name=care_team_users|type=ArrayField[int]|notes=Platform-maintained denormalized cache of user IDs derived from <code>care_team</code> via <code>sync_care_team_users_cache()</code> on every save}}
|}

=== Organization cache, tags & extensions ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Encounter|section=Organization cache, tags & extensions|name=facility_organization_cache|type=ArrayField[int]|notes=Platform-maintained cache of facility-[[References/Organization}}
{{Field|model=Encounter|section=Organization cache, tags & extensions|name=tags|type=ArrayField[int]|notes=Tag IDs applied to the encounter. Serialized via <code>SingleFacilityTagManager().render_tags()</code>}}
{{Field|model=Encounter|section=Organization cache, tags & extensions|name=extensions|type=JSONField|notes=Default <code>{}</code>. Open extension bag for deployment-specific metadata. Validated by <code>ExtensionValidator</code> against <code>ExtensionResource.encounter</code>}}
|}

== Nested JSON shapes ==

=== <code>PeriodSpec</code> (<code>period</code>) ===

Defined in [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/base.py <code>resources/base.py</code>].

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Encounter|section=PeriodSpec (period)|name=start|type=datetime | None|notes=Must be timezone-aware if provided}}
{{Field|model=Encounter|section=PeriodSpec (period)|name=end|type=datetime | None|notes=Must be timezone-aware if provided}}
|}

<code>validate_period</code> rejects naive datetimes, and when both <code>start</code> and <code>end</code> are set it requires <code>start</code> not to exceed <code>end</code>.

=== <code>HospitalizationSpec</code> (<code>hospitalization</code>) ===

Defined in <code>spec.py</code>. All fields optional/nullable.

{| class="wikitable"
|-
! Field
! Type
! Values
|-
| <code>re_admission</code>
| <code>bool | None</code>
| —
|-
| <code>admit_source</code>
| <code>AdmitSourcesChoices | None</code>
| see [[#admit-source-values-admitsourceschoices
|-
| <code>discharge_disposition</code>
| <code>DischargeDispositionChoices | None</code>
| see [[#discharge-disposition-values-dischargedispositionchoices
|-
| <code>diet_preference</code>
| <code>DietPreferenceChoices | None</code>
| see [[#diet-preference-values-dietpreferencechoices
|}

== Enum values ==

=== Status values (<code>StatusChoices</code>) ===

{| class="wikitable"
|-
! Value
!
|-
| <code>planned</code>
|
|-
| <code>in_progress</code>
|
|-
| <code>on_hold</code>
|
|-
| <code>discharged</code>
|
|-
| <code>completed</code>
| terminal (in <code>COMPLETED_CHOICES</code>)
|-
| <code>cancelled</code>
| terminal (in <code>COMPLETED_CHOICES</code>)
|-
| <code>discontinued</code>
| terminal (in <code>COMPLETED_CHOICES</code>)
|-
| <code>entered_in_error</code>
| terminal (in <code>COMPLETED_CHOICES</code> and <code>ERROR_CHOICES</code>)
|-
| <code>unknown</code>
|
|}

<code>COMPLETED_CHOICES = [completed, cancelled, entered_in_error, discontinued]</code>; <code>ERROR_CHOICES = [entered_in_error]</code>.

=== Class values (<code>ClassChoices</code>) ===

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>imp</code>
| inpatient
|-
| <code>amb</code>
| ambulatory
|-
| <code>obsenc</code>
| observation
|-
| <code>emer</code>
| emergency
|-
| <code>vr</code>
| virtual
|-
| <code>hh</code>
| home health
|}

=== Priority values (<code>EncounterPriorityChoices</code>) ===

{| class="wikitable"
|-
! Value
|-
| <code>ASAP</code>
|-
| <code>callback_results</code>
|-
| <code>callback_for_scheduling</code>
|-
| <code>elective</code>
|-
| <code>emergency</code>
|-
| <code>preop</code>
|-
| <code>as_needed</code>
|-
| <code>routine</code>
|-
| <code>rush_reporting</code>
|-
| <code>stat</code>
|-
| <code>timing_critical</code>
|-
| <code>use_as_directed</code>
|-
| <code>urgent</code>
|}

=== Admit source values (<code>AdmitSourcesChoices</code>) ===

{| class="wikitable"
|-
! Value
! Display (<code>get_admit_source_display</code>)
|-
| <code>hosp_trans</code>
| Transferred from other hospital
|-
| <code>emd</code>
| From accident/emergency department
|-
| <code>outp</code>
| From outpatient department
|-
| <code>born</code>
| Born in hospital
|-
| <code>gp</code>
| General Practitioner referral
|-
| <code>mp</code>
| Medical Practitioner/physician referral
|-
| <code>nursing</code>
| From nursing home
|-
| <code>psych</code>
| From psychiatric hospital
|-
| <code>rehab</code>
| From rehabilitation facility
|-
| <code>other</code>
| Other
|}

=== Discharge disposition values (<code>DischargeDispositionChoices</code>) ===

{| class="wikitable"
|-
! Value
! Display (<code>get_discharge_disposition_display</code>)
|-
| <code>home</code>
| Home
|-
| <code>alt_home</code>
| Alternate Home
|-
| <code>other_hcf</code>
| Other Health Care Facility
|-
| <code>hosp</code>
| Hospital
|-
| <code>long</code>
| Long-term Care Facility
|-
| <code>aadvice</code>
| Against Medical Advice
|-
| <code>exp</code>
| Expired
|-
| <code>psy</code>
| Psychiatric Hospital
|-
| <code>rehab</code>
| Rehabilitation Facility
|-
| <code>snf</code>
| Skilled Nursing Facility
|-
| <code>oth</code>
| Other
|}

=== Diet preference values (<code>DietPreferenceChoices</code>) ===

{| class="wikitable"
|-
! Value
|-
| <code>vegetarian</code>
|-
| <code>dairy_free</code>
|-
| <code>nut_free</code>
|-
| <code>gluten_free</code>
|-
| <code>vegan</code>
|-
| <code>halal</code>
|-
| <code>kosher</code>
|-
| <code>none</code>
|}

== Resource specs (API schema) ==

All specs build on <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. <code>EncounterSpecBase</code> sets <code>__exclude__ = [patient, organizations, facility, appointment, current_location, care_team]</code>; those fields move through hooks or dedicated endpoints rather than direct assignment, which is why the create and read schemas diverge from the raw model.

{| class="wikitable"
|-
! Spec
! Role
! Notes
|-
| <code>EncounterSpecBase</code>
| shared
| Fields: <code>id</code>, <code>status</code>, <code>encounter_class</code>, <code>period</code> (<code>PeriodSpec</code>, default <code>{}</code>), <code>hospitalization</code> (<code>HospitalizationSpec | None</code>, default <code>{}</code>), <code>priority</code>, <code>external_identifier</code>, <code>discharge_summary_advice</code>. <code>__model__ = Encounter</code>
|-
| <code>EncounterCreateSpec</code>
| write · create
| Extends base + <code>ExtensionValidator</code>. Adds <code>patient: UUID4</code>, <code>facility: UUID4</code>, <code>organizations: list[UUID4] = []</code>, <code>appointment: UUID4 | None</code>. Resolves FKs by <code>external_id</code>; validates appointment belongs to the patient and facility
|-
| <code>EncounterUpdateSpec</code>
| write · update
| Extends base + <code>ExtensionValidator</code>. Does not accept <code>patient</code>/<code>facility</code>/<code>organizations</code>/<code>appointment</code> — only mutable fields. Appends to status/class history on change
|-
| <code>EncounterListSpec</code>
| read · list
| Adds serialized <code>patient</code> ([[References/Patient
|-
| <code>EncounterRetrieveSpec</code>
| read · detail
| Extends list + <code>EncounterPermissionsMixin</code>. Adds <code>appointment</code> (<code>TokenBookingReadSpec</code>), <code>created_by</code>/<code>updated_by</code> ([[References/User & Skills
|-
| <code>HospitalizationSpec</code>
| nested
| Plain <code>BaseModel</code>; see shape above
|-
| <code>EncounterCareTeamMemberSpec</code>
| nested (write)
| <code>{ user_id: UUID4, role: Coding }</code>, <code>role</code> bound to the <code>system-practitioner-role-code</code> value set
|-
| <code>EncounterCareTeamMemberWriteSpec</code>
| write · care team
| <code>{ members: list[EncounterCareTeamMemberSpec] }</code>. Dedicated payload for replacing the care team
|}

=== Server-maintained behaviour ===

* '''Status history''': on create, <code>status_history</code> starts as <code>{ "history": [{ status, moved_at }] }</code> carrying the initial status; on update, a new entry is appended only when <code>status</code> changes. <code>encounter_class_history</code> / <code>encounter_class</code> follow the same rule.
* '''FK resolution (create)''': <code>patient</code>, <code>facility</code>, and <code>appointment</code> resolve from <code>external_id</code> (404 if not found). The appointment must belong to the same patient and to a slot whose resource sits in the same facility.
* '''Organizations (create)''': <code>organizations</code>, deduplicated to a list of UUIDs, is stashed on <code>obj._organizations</code>, and the resulting <code>EncounterOrganization</code> rows drive <code>facility_organization_cache</code>.
* '''Discharge advice (update)''': omitting <code>discharge_summary_advice</code> on update clears it to <code>None</code> rather than leaving the prior value.
* '''Care team''': <code>role</code> binds to the <code>PRACTITIONER_ROLE_VALUESET</code> (slug <code>system-practitioner-role-code</code>), a SNOMED CT value set of descendants of <code>223366009</code> (healthcare professional) and <code>224930009</code> (healthcare-related occupation).

== Related models ==

=== <code>EncounterOrganization</code> ===

Associates an encounter with a facility-scoped [[References/Organization|organization]] to drive organization-based access control on encounters.

<syntaxhighlight lang="text">encounter → FK Encounter (CASCADE)
organization → FK FacilityOrganization (CASCADE)</syntaxhighlight>
Saving an <code>EncounterOrganization</code> calls <code>encounter.sync_organization_cache()</code>, which rebuilds the encounter's <code>facility_organization_cache</code>.

== Methods & save behaviour ==

=== <code>sync_care_team_users_cache()</code> ===

When <code>care_team</code> is a list, fills <code>care_team_users</code> with <code>int(entry["user_id"])</code> for each entry, falling back to <code>-1</code> when a <code>user_id</code> is missing. The flat integer array lets queries skip JSON traversal.

=== <code>sync_organization_cache()</code> ===

Recomputes <code>facility_organization_cache</code> as the union of:

* every linked <code>EncounterOrganization</code> organization plus its <code>parent_cache</code> chain, and
* the facility's <code>default_internal_organization_id</code>.

Persists the result with <code>super().save(update_fields=["facility_organization_cache"])</code>.

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

On every save:

# <code>sync_care_team_users_cache()</code> runs, refreshing <code>care_team_users</code>.
# A record with no <code>pk</code> is flagged as newly <code>created</code>.
# Inside a single <code>transaction.atomic()</code> block, the base <code>save()</code> runs. For newly created encounters, <code>evaluate_patient_facility_default_values(patient, facility)</code> then generates facility-scoped patient identifier defaults.
# After the transaction, <code>sync_organization_cache()</code> runs, performing a second write (<code>update_fields=["facility_organization_cache"]</code>).

Expect two write passes per create or update through the ORM, plus identifier-default generation on creation.

== API integration notes ==

* Reads use <code>EncounterListSpec</code> / <code>EncounterRetrieveSpec</code>; writes use <code>EncounterCreateSpec</code> / <code>EncounterUpdateSpec</code>.
* <code>status</code>, <code>encounter_class</code>, and <code>priority</code> are required on write and validated against their enums, even though the DB columns are nullable.
* Never set <code>status_history</code>, <code>encounter_class_history</code>, <code>care_team_users</code>, or <code>facility_organization_cache</code> from a client; the server appends history on create and update and derives the caches from <code>care_team</code> and <code>EncounterOrganization</code>.
* Create and update don't touch the care team. Replace it through the dedicated care-team endpoint with <code>EncounterCareTeamMemberWriteSpec</code>, where each member's <code>role</code> must resolve within the <code>system-practitioner-role-code</code> value set.
* <code>period</code> and <code>hospitalization</code> carry structured JSON matching the nested-spec shapes above; <code>period.start</code> and <code>period.end</code> must be timezone-aware.
* <code>current_location</code> is a cached convenience field. The authoritative record is <code>location_history</code>, from <code>FacilityLocationEncounter</code>.
* <code>extensions</code> holds custom key-value data without a schema migration, validated by <code>ExtensionValidator</code>.

{{Related}}

References/Encounter - Revision history

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

Admin: OHC identity seed