Clinical care

Activity Definition

An ActivityDefinition is a FHIR-aligned, facility-scoped template for a clinical activity. It stores the defaults needed to spin up a downstream resource — currently a Service Request — and you "apply" it against an encounter, which merges…

3.1 · versioned documentation · 7 min read

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

Source:

• Model: care/emr/models/activity_definition.py
• Resource specs: spec.py · valueset.py · service_request.py

The Django model is just storage. Several fields are opaque JSONFields or integer ArrayFields 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

ActivityDefinition extends SlugBaseModel, which adds a facility-scoped slug on top of EMRBaseModel. From EMRBaseModel it inherits external_id, created_date/modified_date, soft-delete via deleted, created_by/updated_by, and the history/meta JSON fields. See Base model.

ActivityDefinition 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

Descriptive metadata

Coded clinical attributes (JSON)

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

Requirement & linkage arrays

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

ExtendedSlugType: 7–88 chars, URL-safe, must start with f- or i-. SlugType (used for slug_value): 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.

Service relationships

Enum values

ActivityDefinitionStatusOptions (status)

ActivityDefinitionKindOptions (kind)

ActivityDefinitionCategoryOptions (classification)

Bound value sets

Resource specs (API schema)

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

Server-side behaviour

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

Methods & save behaviour

• Apply → Service Request (service_request.py): convert_ad_to_sr(activity_definition, encounter) builds a draft ServiceRequest. It carries over title, category, code, body_site, locations, and healthcare_service, and binds patient/encounter from the encounter. The new request starts at status=draft, intent=proposal, priority=routine, do_not_perform=False.
• Charge items on apply: apply_ad_charge_definitions(activity_definition, encounter, service_request) loads every linked Charge Item Definition and, for each, instantiates a Charge Item (via apply_charge_item_definition), tags it to the service request (service_resource = service_request, service_resource_id = external_id), copies the creator, and sets performer_actor to the request's requester when one is set.
• version and latest form an append-only chain per slug: query latest=True 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 slug as slug_value. Reference specimen_requirements, observation_result_requirements, charge_item_definitions, and category by external slug (ExtendedSlugType, f-/i- prefixed); reference locations and healthcare_service by UUID.
• code is required and must validate against the activity-definition-procedure-code value set. body_site and each entry of diagnostic_report_codes validate against their bound value sets.
• Apply instantiates the target kind (only service_request today) by merging stored defaults with the encounter, and instantiates any linked charge_item_definitions 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

• Reference: Service Request
• Reference: Specimen Definition
• Reference: Observation Definition
• Reference: Charge Item Definition
• Reference: Healthcare Service
• Reference: Location
• Reference: Resource Category
• Reference: Base model
• Source: activity_definition.py (model)
• Source: spec.py (resource specs)
• Source: valueset.py (procedure-code value set)
• Source: service_request.py (apply logic)

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/definitions/activity-definition.mdx:1 · f6e9f05f