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

2026-07-06T04:05:58Z

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

← Older revision		Revision as of 09:35, 6 July 2026
Line 341:		Line 341:
	* <code>metadata</code> (the model column) is plugin-owned; clients read deployment-specific data back through the <code>care_metadata</code> virtual field, not <code>metadata</code>.		* <code>metadata</code> (the model column) is plugin-owned; clients read deployment-specific data back through the <code>care_metadata</code> virtual field, not <code>metadata</code>.
	* <code>facility_organization_cache</code> is platform-maintained — don't set it directly. The list endpoint scopes results to devices whose cache overlaps the requesting user's facility-organization memberships, or, when <code>?location=</code> is supplied, by location permission / <code>parent_cache</code> with <code>?include_children=</code>.		* <code>facility_organization_cache</code> is platform-maintained — don't set it directly. The list endpoint scopes results to devices whose cache overlaps the requesting user's facility-organization memberships, or, when <code>?location=</code> is supplied, by location permission / <code>parent_cache</code> with <code>?include_children=</code>.

			{{Navbox facility}}

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

Admin: OHC identity seed

2026-07-04T22:44:56Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=facility
|title=Device
|order=7
|introduced=3.0
|model=Device
|reference=References/Encounter
}}

A <code>Device</code> tracks a physical or logical piece of equipment within a facility — from its lifecycle status to where it's placed and which encounter it's attached to.

The Django model is only the storage layer; it types fields loosely — <code>CharField</code> for status enums, <code>JSONField</code> for <code>contact</code>/<code>metadata</code>. The contract lives in the Pydantic resource specs under <code>care/emr/resources/device/</code>, which constrain those <code>CharField</code>s to enums, structure the JSON fields, and define validation, read/write schemas, and server-maintained side effects.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/device.py <code>care/emr/models/device.py</code>]
* Spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/device/spec.py <code>care/emr/resources/device/spec.py</code>]
* History spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/device/history_spec.py <code>care/emr/resources/device/history_spec.py</code>]
* Viewset: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/api/viewsets/device.py <code>care/emr/api/viewsets/device.py</code>]
* Device-type registry: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/registries/device_type/device_registry.py <code>care/emr/registries/device_type/device_registry.py</code>]

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>Device</code>
| A physical or logical device tracked within a facility
|-
| <code>DeviceEncounterHistory</code>
| Records each period a device was associated with an <code>Encounter</code>
|-
| <code>DeviceLocationHistory</code>
| Records each period a device was placed at a <code>FacilityLocation</code>
|-
| <code>DeviceServiceHistory</code>
| Records servicing/maintenance events for a device
|}

All models extend [[References/Base models & conventions|<code>EMRBaseModel</code>]] (shared Care EMR base with <code>external_id</code>, audit fields, and soft-delete semantics).

== <code>Device</code> fields ==

=== Device data ===

{| class="wikitable"
|-
! Field
! Type
! Spec constraint
! Notes
{{Field|model=Device|section=Device data|name=identifier|type=CharField(1024)|notes=<code>str | None</code>}}
{{Field|model=Device|section=Device data|name=status|type=CharField(16)|notes=<code>DeviceStatusChoices</code> ('''required''')}}
{{Field|model=Device|section=Device data|name=availability_status|type=CharField(14)|notes=<code>DeviceAvailabilityStatusChoices</code> ('''required''')}}
{{Field|model=Device|section=Device data|name=manufacturer|type=CharField(1024)|notes=<code>str | None</code>}}
{{Field|model=Device|section=Device data|name=manufacture_date|type=DateTimeField|notes=<code>datetime | None</code>}}
{{Field|model=Device|section=Device data|name=expiration_date|type=DateTimeField|notes=<code>datetime | None</code>}}
{{Field|model=Device|section=Device data|name=lot_number|type=CharField(1024)|notes=<code>str | None</code>}}
{{Field|model=Device|section=Device data|name=serial_number|type=CharField(1024)|notes=<code>str | None</code>}}
{{Field|model=Device|section=Device data|name=registered_name|type=CharField(1024)|notes=<code>str</code> ('''required''')}}
{{Field|model=Device|section=Device data|name=user_friendly_name|type=CharField(1024)|notes=<code>str | None</code>}}
{{Field|model=Device|section=Device data|name=model_number|type=CharField(1024)|notes=<code>str | None</code>}}
{{Field|model=Device|section=Device data|name=part_number|type=CharField(1024)|notes=<code>str | None</code>}}
{{Field|model=Device|section=Device data|name=contact|type=JSONField (default {})|notes=<code>list[ContactPoint]</code> (default <code>[]</code>)}}
{{Field|model=Device|section=Device data|name=care_type|type=CharField(1024) (default None)|notes=<code>str | None</code> (create only)}}
{{Field|model=Device|section=Device data|name=metadata|type=JSONField (default {})|notes=not exposed directly}}
|}

==== Virtual / spec-only field ====

{| class="wikitable"
|-
! Field
! Spec type
! Notes
|-
| <code>care_metadata</code>
| <code>dict</code> (default <code>{}</code>)
| Not a DB column. On read it's populated by the <code>care_type</code> plugin — <code>DeviceListSpec</code> calls the plugin's <code>list(obj)</code>, <code>DeviceRetrieveSpec</code> calls <code>retrieve(obj)</code>. On write it carries plugin-specific data for <code>handle_create</code>/<code>handle_update</code>, which typically persist into the model's <code>metadata</code> column. Falls back to <code>{}</code> when there's no <code>care_type</code> or the plugin lookup fails
|}

=== Relations ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Device|section=Relations|name=facility|type=FK → Facility|notes=<code>CASCADE</code>; owning facility (required). Set server-side from the URL (<code>facility_external_id</code>), never from the request body}}
{{Field|model=Device|section=Relations|name=managing_organization|type=FK → FacilityOrganization|notes=<code>SET_NULL</code>, nullable; org responsible for the device. Excluded from the create/update body — managed via dedicated endpoints (see [[#api-integration-notes}}
{{Field|model=Device|section=Relations|name=current_location|type=FK → FacilityLocation|notes=<code>SET_NULL</code>, nullable; where the device is currently placed. Excluded from the create/update body — managed via <code>associate_location</code>}}
{{Field|model=Device|section=Relations|name=current_encounter|type=FK → Encounter|notes=<code>SET_NULL</code>, nullable; encounter the device is currently attached to. Excluded from the create/update body — managed via <code>associate_encounter</code>}}
|}

=== Access cache ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Device|section=Access cache|name=facility_organization_cache|type=ArrayField[int]|notes=Denormalized cache of facility-organization IDs, rebuilt on every <code>save()</code>. Don't set it directly. <code>get_queryset</code> reads it to scope which devices a user may see}}
|}

== Enum values ==

=== <code>DeviceStatusChoices</code> values ===

<code>status</code> field. Defined in <code>spec.py</code>.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>active</code>
| Device is in service
|-
| <code>inactive</code>
| Device is not currently in service
|-
| <code>entered_in_error</code>
| Record created in error
|}

=== <code>DeviceAvailabilityStatusChoices</code> values ===

<code>availability_status</code> field. Defined in <code>spec.py</code>.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>lost</code>
| Device cannot be located
|-
| <code>damaged</code>
| Device is damaged
|-
| <code>destroyed</code>
| Device is destroyed
|-
| <code>available</code>
| Device is available for use
|}

=== <code>ContactPoint</code> shape ===

<code>contact</code> is <code>list[ContactPoint]</code>. Each item (from <code>care/emr/resources/common/contact_point.py</code>):

<syntaxhighlight lang="text">ContactPoint {
system: ContactPointSystemChoices # required
value: str # required
use: ContactPointUseChoices # required
}</syntaxhighlight>
{| class="wikitable"
|-
! <code>system</code> values
! <code>use</code> values
|-
| <code>phone</code>, <code>fax</code>, <code>email</code>, <code>pager</code>, <code>url</code>, <code>sms</code>, <code>other</code>
| <code>home</code>, <code>work</code>, <code>temp</code>, <code>old</code>, <code>mobile</code>
|}

== Related models ==

=== <code>DeviceEncounterHistory</code> ===

Audit trail of device-to-encounter associations. Attaching a device to an encounter creates a new row; detaching it stamps <code>end</code>. Read-only via the API (<code>EMRModelReadOnlyViewSet</code>), ordered by <code>-end</code>.

<syntaxhighlight lang="text">device → FK Device (CASCADE)
encounter → FK Encounter (CASCADE)
start → DateTimeField
end → DateTimeField (nullable)</syntaxhighlight>
=== <code>DeviceLocationHistory</code> ===

Audit trail of device placements. Moving a device to a location creates a new row; leaving it stamps <code>end</code>. Read-only via the API, ordered by <code>-end</code>.

<syntaxhighlight lang="text">device → FK Device (CASCADE)
location → FK FacilityLocation (CASCADE)
start → DateTimeField
end → DateTimeField (nullable)</syntaxhighlight>
=== <code>DeviceServiceHistory</code> ===

Servicing/maintenance log for a device. Writable via the API (create + update + list + retrieve).

<syntaxhighlight lang="text">device → FK Device (PROTECT, required)
serviced_on → DateTimeField (nullable, default None)
note → TextField (default "")
edit_history → JSONField (default [])</syntaxhighlight>
<code>device</code> uses <code>PROTECT</code>, so a <code>Device</code> with service-history rows can't be hard-deleted while those rows exist. <code>edit_history</code> is an append-only audit list the server maintains on every update (see [[#deviceservicehistory-edit-history|Methods & save behaviour]]).

== Resource specs (API schema) ==

The viewset wires these specs as create = <code>DeviceCreateSpec</code>, update = <code>DeviceUpdateSpec</code>, list = <code>DeviceListSpec</code>, retrieve = <code>DeviceRetrieveSpec</code>. All extend <code>EMRResource</code> (<code>serialize</code> / <code>de_serialize</code>, with <code>perform_extra_serialization</code> / <code>perform_extra_deserialization</code> hooks).

=== Device specs ===

{| class="wikitable"
|-
! Spec class
! Role
! Adds / overrides
! Excludes
|-
| <code>DeviceSpecBase</code>
| shared base
| <code>id</code>, all device-data fields, <code>status</code>/<code>availability_status</code> enums, <code>contact: list[ContactPoint]</code>, <code>registered_name</code> required
| <code>facility</code>, <code>managing_organization</code>, <code>current_location</code>, <code>current_encounter</code>, <code>care_metadata</code>
|-
| <code>DeviceCreateSpec</code>
| write · create
| <code>care_type</code> (validated against <code>DeviceTypeRegistry</code>), <code>care_metadata: dict</code>
| (inherits base excludes)
|-
| <code>DeviceUpdateSpec</code>
| write · update
| <code>care_metadata: dict</code> — no <code>care_type</code>, which makes <code>care_type</code> immutable after create
| (inherits base excludes)
|-
| <code>DeviceListSpec</code>
| read · list
| <code>id = external_id</code>; <code>care_metadata</code> from plugin <code>list(obj)</code>
| (inherits)
|-
| <code>DeviceRetrieveSpec</code>
| read · detail
| full nested objects: <code>current_location</code> (<code>FacilityLocationListSpec</code>), <code>current_encounter</code> (<code>EncounterListSpec</code>), <code>managing_organization</code> (<code>FacilityOrganizationReadSpec</code>), <code>created_by</code>/<code>updated_by</code> (audit users); <code>care_metadata</code> from plugin <code>retrieve(obj)</code>
| (inherits)
|}

=== Device history specs ===

{| class="wikitable"
|-
! Spec class
! Role
! Fields
! Excludes
|-
| <code>DeviceLocationHistoryListSpec</code>
| read · list
| <code>id</code>, <code>location</code> (nested <code>FacilityLocationListSpec</code>), <code>created_by</code>, <code>start</code>, <code>end?</code>
| <code>device</code>, <code>location</code> (raw FK)
|-
| <code>DeviceEncounterHistoryListSpec</code>
| read · list
| <code>id</code>, <code>encounter</code> (nested <code>EncounterListSpec</code>), <code>created_by</code>, <code>start</code>, <code>end?</code>
| <code>device</code>, <code>encounter</code> (raw FK)
|-
| <code>DeviceServiceHistorySpecBase</code>
| shared base
| <code>id</code>
| <code>device</code>, <code>edit_history</code>
|-
| <code>DeviceServiceHistoryWriteSpec</code>
| write
| <code>serviced_on: datetime</code> (required), <code>note: str</code> (required)
| (inherits)
|-
| <code>DeviceServiceHistoryListSpec</code>
| read · list
| adds <code>created_date</code>, <code>modified_date</code>; <code>id = external_id</code>
| (inherits)
|-
| <code>DeviceServiceHistoryRetrieveSpec</code>
| read · detail
| adds <code>edit_history: list[dict]</code> (each entry's <code>updated_by</code> hydrated to a <code>UserSpec</code> from cache), <code>created_by</code>, <code>updated_by</code>
| (inherits)
|}

=== Validation rules ===

* <code>status</code> and <code>availability_status</code> must each match one of their enum values, or the request is rejected.
* <code>registered_name</code> is required on every write.
* <code>care_type</code> (create only) must be a registered device-type key or <code>null</code>. <code>DeviceCreateSpec.validate_care_type</code> calls <code>DeviceTypeRegistry.get_care_device_class(value)</code>, which raises for unknown types.
* <code>care_type</code> can't change on update — <code>DeviceUpdateSpec</code> doesn't expose it.
* <code>DeviceServiceHistory.serviced_on</code> and <code>note</code> are required on write; updates are blocked once <code>edit_history</code> reaches 50 entries (<code>"Cannot Edit instance anymore"</code>).
* <code>ContactPoint.system</code>, <code>value</code>, and <code>use</code> are all required for each contact entry.

== Methods & save behaviour ==

=== <code>Device.save()</code> — organization cache ===

Every save rebuilds <code>facility_organization_cache</code>:

# Look up the <code>FacilityOrganization</code> with <code>org_type="root"</code> for the device's <code>facility</code>; its ID seeds the cache.
# If <code>managing_organization</code> is set, add its <code>id</code> and its <code>parent_cache</code> (the full ancestor chain).
# Persist the resulting set as <code>facility_organization_cache</code>.

This lets the list endpoint filter by organization hierarchy without traversing joins. Treat the cache as platform-maintained; <code>managing_organization</code> and <code>facility</code> are the writable inputs that drive it.

=== <code>care_type</code> plugin hooks ===

When <code>care_type</code> is set, the matching <code>DeviceTypeBase</code> subclass from <code>DeviceTypeRegistry</code> runs inside the create/update/delete transaction:

{| class="wikitable"
|-
! Stage
! Hook
! Effect
|-
| create
| <code>handle_create(request_data, obj)</code>
| May mutate <code>obj</code> / <code>obj.metadata</code> and persist (e.g. the bundled <code>camera</code> plugin stores <code>request_data["some_data"]</code> into <code>metadata</code>)
|-
| update
| <code>handle_update(request_data, obj)</code>
| Same, on update
|-
| destroy
| <code>handle_delete(obj)</code>
| Validation/cleanup before the device is soft-deleted (<code>deleted=True</code>)
|-
| list
| <code>list(obj)</code>
| Supplies <code>care_metadata</code> for <code>DeviceListSpec</code>
|-
| retrieve
| <code>retrieve(obj)</code>
| Supplies <code>care_metadata</code> for <code>DeviceRetrieveSpec</code>
|}

=== <code>DeviceServiceHistory</code> edit history ===

On <code>perform_update</code>, the viewset snapshots the current DB row and appends <code>{serviced_on, note, updated_by}</code> to <code>edit_history</code> before writing the new values — a server-maintained, append-only trail of previous states. Updates are refused once it holds 50 entries.

== API integration notes ==

* <code>facility</code> comes from the URL (<code>facility_external_id</code>) on create, not from the body.
* <code>current_location</code>, <code>current_encounter</code>, and <code>managing_organization</code> aren't writable through the device create/update body. Dedicated detail actions mutate them, and each one closes the open history row (stamps <code>end</code>) before opening a new one:
** <code>POST associate_encounter</code> — <code>{ encounter: uuid | null }</code>; closes the open <code>DeviceEncounterHistory</code>, sets <code>current_encounter</code>, and opens (and returns) a new history row. <code>null</code> detaches.
** <code>POST associate_location</code> — <code>{ location: uuid | null }</code>; same pattern against <code>DeviceLocationHistory</code>.
** <code>POST add_managing_organization</code> — <code>{ managing_organization: uuid }</code>.
** <code>POST remove_managing_organization</code> — clears <code>managing_organization</code>.
* When an encounter reaches a completed status, <code>disassociate_device_from_encounter</code> clears <code>current_encounter</code> on all attached devices and stamps <code>end</code> on their open <code>DeviceEncounterHistory</code> rows.
* <code>metadata</code> (the model column) is plugin-owned; clients read deployment-specific data back through the <code>care_metadata</code> virtual field, not <code>metadata</code>.
* <code>facility_organization_cache</code> is platform-maintained — don't set it directly. The list endpoint scopes results to devices whose cache overlaps the requesting user's facility-organization memberships, or, when <code>?location=</code> is supplied, by location permission / <code>parent_cache</code> with <code>?include_children=</code>.

{{Related}}

References/Device - Revision history

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

Admin: OHC identity seed