References/Activity Definition

referencedefinitionsCARE 3.0+

Definitions

Concepts

Questionnaire

Response Template Value Set Observation Definition Specimen Definition Activity Definition Charge Item Definition

Product Knowledge

References

Questionnaire

Response Template Value Set Observation Definition Specimen Definition Activity Definition Charge Item Definition

Product Knowledge

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 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: [https://github.com/ohcnetwork/care/blob/develop/care/emr/models/activity_definition.py care/emr/models/activity_definition.py]
• Resource specs: [https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/activity_definition/spec.py spec.py] · [https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/activity_definition/valueset.py valueset.py] · [https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/activity_definition/service_request.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

Model	Purpose
ActivityDefinition	Versioned, facility-scoped template describing a clinical activity and the defaults used to create the resources it produces

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

Field	Storage type	API shape / notes
facility	FK → facility.Facility (PROTECT)	Owning facility. Spec-__exclude__d — set server-side and never accepted in the payload.
slug	CharField(255)	Facility-scoped identifier. On write you supply it as slug_value (SlugType); perform_extra_deserialization assigns it to obj.slug. On read it comes back as slug plus a parsed slug_config dict.
version	IntegerField	None), serialized on list and retrieve. Drives the append-only version chain.
latest	BooleanField	Default True. Marks the current version within a slug's chain. Server-maintained, not exposed in the specs.
derived_from_uri	TextField	None = None).

Descriptive metadata

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

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.

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

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.

Field	Storage type	Write shape	Read (retrieve) shape
specimen_requirements	ArrayField[int]	list[ExtendedSlugType]	list[dict] — serialized [[References/Specimen Definition
observation_result_requirements	ArrayField[int]	list[ExtendedSlugType]	list[dict] — serialized [[References/Observation Definition
locations	ArrayField[int]	list[UUID4]	list[dict] — serialized [[References/Location
charge_item_definitions	ArrayField[int]	list[ExtendedSlugType]	list[dict] — serialized [[References/Charge Item Definition
tags	ArrayField[int]	not written via spec	list[dict] — rendered via SingleFacilityTagManager().render_tags(obj)

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

Field	Storage type	API shape / notes
healthcare_service	FK → emr.HealthcareService (PROTECT)	None, resolved by external_id in perform_extra_deserialization. Retrieve: serialized via HealthcareServiceReadSpec. See References/Healthcare Service.
category	FK → emr.ResourceCategory (CASCADE)	None, resolved by slug. Read: serialized via ResourceCategoryReadSpec. Deleting the References/Resource Category cascades to the definition.

Enum values

ActivityDefinitionStatusOptions (status)

Value
draft
active
retired
unknown

ActivityDefinitionKindOptions (kind)

Value	Notes
service_request	Only supported kind; applying the definition produces a References/Service Request

ActivityDefinitionCategoryOptions (classification)

Value
laboratory
imaging
counselling
surgical_procedure
education

Bound value sets

Field	Value set slug	Source system / filter
code	activity-definition-procedure-code	SNOMED CT, concept is-a 71388002 (Procedure)
body_site	system-body-site-observation	SNOMED CT body-site concepts
diagnostic_report_codes[]	system-observation	LOINC (http://loinc.org)

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"].

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

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 ([https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/activity_definition/service_request.py 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 References/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.

Definitions

Concepts

Questionnaire · Response Template · Value Set · Obs Definition · Specimen Definition · Activity Definition · Charge Item Definition · Product Knowledge

References

Questionnaire · Response Template · Value Set · Obs Definition · Specimen Definition · Activity Definition · Charge Item Definition · Product Knowledge

Related

Pages that link here:

• Concepts/Activity Definition
• References/Questionnaire

• Reference: References/Base models & conventions

Open Healthcare Network's flagship product: an open-source, FHIR-native electronic medical record (EMR) and healthcare operating system.

Fast Healthcare Interoperability Resources — an HL7 standard for exchanging healthcare data. CARE is built on FHIR R5.

A comprehensive clinical terminology used to code diagnoses, findings and procedures.

Logical Observation Identifiers Names and Codes — a standard for identifying laboratory and clinical observations.