Clinical care

Notes

Notes are threaded discussions attached to a patient. A NoteThread groups messages; a NoteMessage is one message in that thread, carrying a server-maintained edit history. The Django models store the data: NoteThread holds the patient and…

3.1 · versioned documentation · 5 min read

Notes are threaded discussions attached to a patient. A NoteThread groups messages; a NoteMessage is one message in that thread, carrying a server-maintained edit history.

The Django models (care/emr/models/notes.py) store the data: NoteThread holds the patient and optional encounter link, and NoteMessage stores each body next to an opaque message_history JSONField. The Pydantic resource specs (care/emr/resources/notes/) extend EMRResource and define what the API exposes — the shape of message_history, the read/write schema split, and the edit-history logic that runs on every update.

Source:

• Model: care/emr/models/notes.py
• Specs: resources/notes/thread_spec.py, resources/notes/notes_spec.py
• Base: resources/base.py

Models

Both extend EMRBaseModel, which supplies external_id, created_date/modified_date, soft-delete via deleted, created_by/updated_by, and the history/meta JSON fields.

NoteThread fields

A thread with no encounter is patient-level; a thread with an encounter is pinned to that visit. A TODO in the source flags organization-based access restriction as planned but not yet implemented.

Related models

NoteMessage

One message inside a thread.

message_history shape

The update spec writes a fixed structure, not a free-form blob. Each edit appends the previous message body to a history list:

{
  "history": [
    {
      "message": "string",           // the prior message body (pre-edit)
      "created_by": {
        "username": "string",
        "external_id": "uuid"        // editor of the prior version
      },
      "edited_at": "datetime str",   // timezone.now() at the time of this edit
      "created_at": "datetime str"   // the prior version's modified_date
    }
    // ... one entry per edit, oldest first
  ]
}

Clients never write message_history. It is read-only on the API and rebuilt server-side on each edit (see NoteMessageUpdateSpec below).

Resource specs (API schema)

Every spec extends EMRResource (resources/base.py), which provides serialize (DB object → pydantic, via perform_extra_serialization) and de_serialize (pydantic → DB object, via perform_extra_deserialization). Fields named in __exclude__ are skipped in both directions and handled by hand.

Thread specs

Validation and server behaviour:

• title is required on write at the spec layer (Field(..., max_length=255)), even though the column is nullable.
• NoteThreadCreateSpec.encounter runs validate_encounter_exists: a non-null value must match an existing Encounter.external_id, or it raises ValueError("Encounter not found").
• On create, perform_extra_deserialization looks up the Encounter by external_id and assigns the FK. patient belongs to no thread spec — it comes from the request context.

Message specs

Validation and server behaviour:

• message is required on create and update.
• thread is never in the request body (__exclude__); it comes from the URL/viewset context.
• On update, NoteMessageUpdateSpec.perform_extra_deserialization fetches the existing NoteMessage by external_id, initializes message_history["history"] = [] if empty, then appends an entry: the prior message, the prior author (username + external_id), edited_at (timezone.now()), and created_at (the prior modified_date). Clients cannot write message_history directly.

Methods & save behaviour

• NoteThread and NoteMessage inherit save and audit behaviour from EMRBaseModel: external_id, created_by/updated_by, created_date/modified_date, and soft delete via deleted.
• Read specs populate audit users through EMRResource.serialize_audit_users, which resolves created_by/updated_by to cached UserSpec dicts.
• message_history changes only inside NoteMessageUpdateSpec.perform_extra_deserialization — never from client input.
• Cascade deletes flow downward: deleting a patient removes its threads, and deleting a thread removes its messages.

API integration notes

Payload field names follow the spec classes above, not the Django model names.

• patient and thread never appear in a request body; they come from the URL/viewset context.
• Send encounter on create as the encounter's external_id (UUID); it is validated to exist. It cannot be reassigned on update.
• title and message are required on write, even though the underlying columns are nullable.
• message_history is read-only. Each edit appends the previous body and authorship to history server-side.
• created_by, updated_by, created_date, and modified_date are read-only audit fields from EMRBaseModel; soft deletes use deleted.

Related

• Source: notes.py on GitHub
• Specs: thread_spec.py, notes_spec.py
• Reference: Patient
• Reference: Encounter
• Reference: Base model

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/clinical/notes.mdx:1 · f6e9f05f