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

2026-07-06T04:03:53Z

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

← Older revision		Revision as of 09:33, 6 July 2026
Line 291:		Line 291:
	* Apply instantiates the target <code>kind</code> (only <code>service_request</code> today) by merging stored defaults with the encounter, and instantiates any linked <code>charge_item_definitions</code> in the same pass.		* Apply instantiates the target <code>kind</code> (only <code>service_request</code> today) by merging stored defaults with the encounter, and instantiates any linked <code>charge_item_definitions</code> in the same pass.
	* The requirement and linkage fields are plain integer ID arrays. Retrieve serialization resolves them to nested objects and skips any ID that no longer resolves, so a response can omit a requirement you stored.		* The requirement and linkage fields are plain integer ID arrays. Retrieve serialization resolves them to nested objects and skips any ID that no longer resolves, so a response can omit a requirement you stored.

			{{Navbox definitions}}

	{{Related}}		{{Related}}

Admin: OHC identity seed

2026-07-04T22:44:36Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=definitions
|title=Activity Definition
|order=6
|introduced=3.0
|model=ActivityDefinition
|reference=References/Base models & conventions
}}

An <code>ActivityDefinition</code> is a FHIR-aligned, facility-scoped template for a clinical activity. It stores the defaults needed to spin up a downstream resource — currently a [[References/Service Request]] — and you "apply" it against an encounter, which merges those defaults with the encounter context to produce the live resource.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/activity_definition.py <code>care/emr/models/activity_definition.py</code>]
* Resource specs: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/activity_definition/spec.py <code>spec.py</code>] · [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/activity_definition/valueset.py <code>valueset.py</code>] · [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/activity_definition/service_request.py <code>service_request.py</code>]

The Django model is just storage. Several fields are opaque <code>JSONField</code>s or integer <code>ArrayField</code>s whose real structure lives in the Pydantic resource specs — the API layer that defines the enums, JSON shapes, validation rules, and the split between read and write schemas. Neither layer is complete on its own; read them together.

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>ActivityDefinition</code>
| Versioned, facility-scoped template describing a clinical activity and the defaults used to create the resources it produces
|}

<code>ActivityDefinition</code> extends <code>SlugBaseModel</code>, which adds a facility-scoped <code>slug</code> on top of <code>EMRBaseModel</code>. From <code>EMRBaseModel</code> it inherits <code>external_id</code>, <code>created_date</code>/<code>modified_date</code>, soft-delete via <code>deleted</code>, <code>created_by</code>/<code>updated_by</code>, and the <code>history</code>/<code>meta</code> JSON fields. See [[References/Base models & conventions|Base model]].

== <code>ActivityDefinition</code> fields ==

Each field lists its storage type (Django model) and, where the spec constrains it, the API shape or values the Pydantic specs enforce.

=== Identity & versioning ===

{| class="wikitable"
|-
! Field
! Storage type
! API shape / notes
|-
| <code>facility</code>
| <code>FK → facility.Facility</code> (PROTECT)
| Owning facility. Spec-<code>__exclude__</code>d — set server-side and never accepted in the payload.
|-
| <code>slug</code>
| <code>CharField(255)</code>
| Facility-scoped identifier. On write you supply it as <code>slug_value</code> (<code>SlugType</code>); <code>perform_extra_deserialization</code> assigns it to <code>obj.slug</code>. On read it comes back as <code>slug</code> plus a parsed <code>slug_config</code> dict.
|-
| <code>version</code>
| <code>IntegerField</code>
| Default <code>1</code>. Read-only in specs (<code>version: int | None</code>), serialized on list and retrieve. Drives the append-only version chain.
|-
| <code>latest</code>
| <code>BooleanField</code>
| Default <code>True</code>. Marks the current version within a slug's chain. Server-maintained, not exposed in the specs.
|-
| <code>derived_from_uri</code>
| <code>TextField</code>
| Nullable. URI this definition was derived from. Optional in specs (<code>str | None = None</code>).
|}

=== Descriptive metadata ===

{| class="wikitable"
|-
! Field
! Storage type
! API shape / notes
|-
| <code>title</code>
| <code>CharField(1024)</code>
| Required (<code>str</code>). Human-friendly name.
|-
| <code>status</code>
| <code>CharField(255)</code>
| Required enum — <code>ActivityDefinitionStatusOptions</code> (<code>draft</code> / <code>active</code> / <code>retired</code> / <code>unknown</code>).
|-
| <code>classification</code>
| <code>CharField(100)</code>
| Required enum — <code>ActivityDefinitionCategoryOptions</code> (<code>laboratory</code> / <code>imaging</code> / <code>counselling</code> / <code>surgical_procedure</code> / <code>education</code>).
|-
| <code>kind</code>
| <code>CharField(100)</code>
| Required enum — <code>ActivityDefinitionKindOptions</code> (only <code>service_request</code>). Determines the resource produced on apply.
|-
| <code>description</code>
| <code>TextField</code>
| Optional in specs; default <code>""</code>.
|-
| <code>usage</code>
| <code>TextField</code>
| Optional in specs; default <code>""</code>.
|}

=== Coded clinical attributes (JSON) ===

These are <code>JSONField</code>s. The spec binds each to a value set via <code>ValueSetBoundCoding[<slug>]</code>, which validates the submitted code against that value set. Every coding is shaped <code>{ system?: str, version?: str, code: str (required), display?: str }</code> with <code>extra="forbid"</code>, so unknown keys are rejected.

{| class="wikitable"
|-
! Field
! Storage type
! API shape / notes
|-
| <code>code</code>
| <code>JSONField</code> (nullable)
| Required <code>Coding</code> bound to value set <code>activity-definition-procedure-code</code> (SNOMED CT, <code>concept is-a 71388002</code> "Procedure"). Nullable in the DB but rejected on write if absent.
|-
| <code>body_site</code>
| <code>JSONField</code> (nullable)
| Optional <code>Coding | None = None</code> bound to value set <code>system-body-site-observation</code> (SNOMED CT body sites).
|-
| <code>diagnostic_report_codes</code>
| <code>JSONField</code> (nullable)
| <code>list[Coding]</code>, default <code>[]</code>. Each <code>Coding</code> bound to value set <code>system-observation</code> (LOINC).
|}

=== Requirement & linkage arrays ===

These store integer primary keys, not Django FK relations — <code>ArrayField(IntegerField, default=list)</code>. The specs never expose those raw PKs: writes reference targets by external slug or UUID, and retrieves expand them back into serialized objects.

{| class="wikitable"
|-
! Field
! Storage type
! Write shape
! Read (retrieve) shape
|-
| <code>specimen_requirements</code>
| <code>ArrayField[int]</code>
| <code>list[ExtendedSlugType]</code>
| <code>list[dict]</code> — serialized [[References/Specimen Definition
|-
| <code>observation_result_requirements</code>
| <code>ArrayField[int]</code>
| <code>list[ExtendedSlugType]</code>
| <code>list[dict]</code> — serialized [[References/Observation Definition
|-
| <code>locations</code>
| <code>ArrayField[int]</code>
| <code>list[UUID4]</code>
| <code>list[dict]</code> — serialized [[References/Location
|-
| <code>charge_item_definitions</code>
| <code>ArrayField[int]</code>
| <code>list[ExtendedSlugType]</code>
| <code>list[dict]</code> — serialized [[References/Charge Item Definition
|-
| <code>tags</code>
| <code>ArrayField[int]</code>
| not written via spec
| <code>list[dict]</code> — rendered via <code>SingleFacilityTagManager().render_tags(obj)</code>
|}

<blockquote><code>ExtendedSlugType</code>: 7–88 chars, URL-safe, must start with <code>f-</code> or <code>i-</code>. <code>SlugType</code> (used for <code>slug_value</code>): 5–50 chars, URL-safe. The stored integer arrays carry no referential integrity — nothing stops you storing an ID whose target is later deleted, and retrieve serialization silently skips any ID that no longer resolves.
</blockquote>
=== Service relationships ===

{| class="wikitable"
|-
! Field
! Storage type
! API shape / notes
|-
| <code>healthcare_service</code>
| <code>FK → emr.HealthcareService</code> (PROTECT)
| Nullable; default <code>None</code>. Write: <code>UUID4 | None</code>, resolved by <code>external_id</code> in <code>perform_extra_deserialization</code>. Retrieve: serialized via <code>HealthcareServiceReadSpec</code>. See [[References/Healthcare Service]].
|-
| <code>category</code>
| <code>FK → emr.ResourceCategory</code> (CASCADE)
| Nullable. Write: <code>ExtendedSlugType | None</code>, resolved by <code>slug</code>. Read: serialized via <code>ResourceCategoryReadSpec</code>. Deleting the [[References/Resource Category]] cascades to the definition.
|}

== Enum values ==

=== <code>ActivityDefinitionStatusOptions</code> (<code>status</code>) ===

{| class="wikitable"
|-
! Value
|-
| <code>draft</code>
|-
| <code>active</code>
|-
| <code>retired</code>
|-
| <code>unknown</code>
|}

=== <code>ActivityDefinitionKindOptions</code> (<code>kind</code>) ===

{| class="wikitable"
|-
! Value
! Notes
|-
| <code>service_request</code>
| Only supported kind; applying the definition produces a [[References/Service Request]]
|}

=== <code>ActivityDefinitionCategoryOptions</code> (<code>classification</code>) ===

{| class="wikitable"
|-
! Value
|-
| <code>laboratory</code>
|-
| <code>imaging</code>
|-
| <code>counselling</code>
|-
| <code>surgical_procedure</code>
|-
| <code>education</code>
|}

== Bound value sets ==

{| class="wikitable"
|-
! Field
! Value set slug
! Source system / filter
|-
| <code>code</code>
| <code>activity-definition-procedure-code</code>
| SNOMED CT, <code>concept is-a 71388002</code> (Procedure)
|-
| <code>body_site</code>
| <code>system-body-site-observation</code>
| SNOMED CT body-site concepts
|-
| <code>diagnostic_report_codes[]</code>
| <code>system-observation</code>
| LOINC (<code>http://loinc.org</code>)
|}

== Resource specs (API schema) ==

All specs extend <code>EMRResource</code> (see [[References/Base models & conventions|Base model]]), which provides <code>serialize</code> (DB → Pydantic) and <code>de_serialize</code> (Pydantic → DB) plus the <code>perform_extra_serialization</code> / <code>perform_extra_deserialization</code> hooks. Here <code>__model__ = ActivityDefinition</code> and <code>__exclude__ = ["facility"]</code>.

{| class="wikitable"
|-
! Spec class
! Role
! Notes
|-
| <code>BaseActivityDefinitionSpec</code>
| shared base
| <code>id</code>, <code>title</code>, <code>derived_from_uri</code>, <code>status</code>, <code>description</code>, <code>usage</code>, <code>classification</code>, <code>kind</code>, <code>code</code>, <code>body_site</code>, <code>diagnostic_report_codes</code>.
|-
| <code>ActivityDefinitionWriteSpec</code>
| write · create + update
| Adds <code>locations</code> (<code>list[UUID4]</code>), <code>specimen_requirements</code> / <code>observation_result_requirements</code> / <code>charge_item_definitions</code> (<code>list[ExtendedSlugType]</code>), <code>healthcare_service</code> (<code>UUID4 | None</code>), <code>category</code> (<code>ExtendedSlugType | None</code>), <code>slug_value</code> (<code>SlugType</code>).
|-
| <code>ActivityDefinitionReadSpec</code>
| read · list
| Base fields plus <code>version</code>, <code>tags</code>, <code>category</code> (serialized dict), <code>slug</code>, <code>slug_config</code>.
|-
| <code>ActivityDefinitionRetrieveSpec</code>
| read · detail
| Extends <code>ReadSpec</code>; expands <code>specimen_requirements</code>, <code>observation_result_requirements</code>, <code>locations</code>, <code>healthcare_service</code>, <code>charge_item_definitions</code> from ID arrays into fully serialized nested objects.
|}

=== Server-side behaviour ===

* '''<code>ActivityDefinitionWriteSpec.perform_extra_deserialization</code>''' (write path):
** Resolves <code>healthcare_service</code> by <code>external_id</code>, or clears it to <code>None</code> when absent.
** Resolves <code>category</code> by <code>slug</code>, only when provided.
** Assigns <code>obj.slug = self.slug_value</code>.
* '''<code>ActivityDefinitionReadSpec.perform_extra_serialization</code>''' (read path): sets <code>id = external_id</code>, renders <code>tags</code>, serializes <code>category</code> (when present) via <code>ResourceCategoryReadSpec</code>, and parses <code>slug_config = obj.parse_slug(obj.slug)</code>.
* '''<code>ActivityDefinitionRetrieveSpec.perform_extra_serialization</code>''': calls the parent, then resolves each ID array (<code>specimen_requirements</code>, <code>observation_result_requirements</code>, <code>locations</code>, <code>charge_item_definitions</code>) against its model — dropping IDs that no longer exist — and serializes <code>healthcare_service</code>.
* The base <code>de_serialize</code> writes only model-mapped fields with <code>exclude_defaults=True</code>, so any unset optional field falls back to its model default.

== Methods & save behaviour ==

* '''Apply → Service Request''' ([<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/activity_definition/service_request.py <code>service_request.py</code>]): <code>convert_ad_to_sr(activity_definition, encounter)</code> builds a draft [[References/Service Request|<code>ServiceRequest</code>]]. It carries over <code>title</code>, <code>category</code>, <code>code</code>, <code>body_site</code>, <code>locations</code>, and <code>healthcare_service</code>, and binds <code>patient</code>/<code>encounter</code> from the encounter. The new request starts at <code>status=draft</code>, <code>intent=proposal</code>, <code>priority=routine</code>, <code>do_not_perform=False</code>.
* '''Charge items on apply''': <code>apply_ad_charge_definitions(activity_definition, encounter, service_request)</code> loads every linked [[References/Charge Item Definition]] and, for each, instantiates a Charge Item (via <code>apply_charge_item_definition</code>), tags it to the service request (<code>service_resource = service_request</code>, <code>service_resource_id = external_id</code>), copies the creator, and sets <code>performer_actor</code> to the request's <code>requester</code> when one is set.
* <code>version</code> and <code>latest</code> form an append-only chain per <code>slug</code>: query <code>latest=True</code> for the current definition; superseded versions stay readable so existing references don't break.

== API integration notes ==

* Payload field names follow the Pydantic specs, not the Django model. Send <code>slug</code> as <code>slug_value</code>. Reference <code>specimen_requirements</code>, <code>observation_result_requirements</code>, <code>charge_item_definitions</code>, and <code>category</code> by external slug (<code>ExtendedSlugType</code>, <code>f-</code>/<code>i-</code> prefixed); reference <code>locations</code> and <code>healthcare_service</code> by UUID.
* <code>code</code> is required and must validate against the <code>activity-definition-procedure-code</code> value set. <code>body_site</code> and each entry of <code>diagnostic_report_codes</code> validate against their bound value sets.
* Apply instantiates the target <code>kind</code> (only <code>service_request</code> today) by merging stored defaults with the encounter, and instantiates any linked <code>charge_item_definitions</code> in the same pass.
* The requirement and linkage fields are plain integer ID arrays. Retrieve serialization resolves them to nested objects and skips any ID that no longer resolves, so a response can omit a requirement you stored.

{{Related}}

References/Activity Definition - Revision history

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

Admin: OHC identity seed