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

2026-07-06T04:04:37Z

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

← Older revision		Revision as of 09:34, 6 July 2026
Line 178:		Line 178:
	* <code>message_history</code> is read-only. Each edit appends the previous body and authorship to <code>history</code> server-side.		* <code>message_history</code> is read-only. Each edit appends the previous body and authorship to <code>history</code> server-side.
	* <code>created_by</code>, <code>updated_by</code>, <code>created_date</code>, and <code>modified_date</code> are read-only audit fields from <code>EMRBaseModel</code>; soft deletes use <code>deleted</code>.		* <code>created_by</code>, <code>updated_by</code>, <code>created_date</code>, and <code>modified_date</code> are read-only audit fields from <code>EMRBaseModel</code>; soft deletes use <code>deleted</code>.

			{{Navbox clinical}}

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

Admin: OHC identity seed

2026-07-04T22:44:23Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=clinical
|title=Notes
|order=9
|introduced=3.0
|fhir=Notes
|model=Notes
|reference=References/Base models & conventions
}}

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

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

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/notes.py <code>care/emr/models/notes.py</code>]
* Specs: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/notes/thread_spec.py <code>resources/notes/thread_spec.py</code>], [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/notes/notes_spec.py <code>resources/notes/notes_spec.py</code>]
* Base: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/base.py <code>resources/base.py</code>]

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>NoteThread</code>
| A discussion thread attached to a patient (optionally scoped to an encounter)
|-
| <code>NoteMessage</code>
| An individual message posted within a <code>NoteThread</code>
|}

Both extend [[References/Base models & conventions|<code>EMRBaseModel</code>]], which supplies <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.

== <code>NoteThread</code> fields ==

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Notes|section=NoteThread fields|name=title|type=CharField(255)|notes=Nullable and blank-allowed in the column, but the spec requires it on write (<code>title: str</code>, <code>max_length=255</code>)}}
{{Field|model=Notes|section=NoteThread fields|name=patient|type=FK → Patient|notes=<code>on_delete=CASCADE</code>; deleting the [[References/Patient}}
{{Field|model=Notes|section=NoteThread fields|name=encounter|type=FK → Encounter|notes=Nullable, blank-allowed, <code>on_delete=CASCADE</code>. Scopes the thread to one [[References/Encounter}}
|}

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

== Related models ==

=== <code>NoteMessage</code> ===

One message inside a thread.

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Notes|section=NoteMessage|name=thread|type=FK → NoteThread|notes=<code>on_delete=CASCADE</code>; deleting the thread deletes its messages. Excluded from spec serialization (<code>__exclude__</code>) and set from the URL/viewset context}}
{{Field|model=Notes|section=NoteMessage|name=message|type=TextField|notes=Free-text body. Required on write (<code>message: str</code>)}}
{{Field|model=Notes|section=NoteMessage|name=message_history|type=JSONField|notes=Defaults to <code>{}</code>. Opaque at the model layer; the spec gives it the shape below and rewrites it server-side on each edit. Read-only on the API}}
|}

==== <code>message_history</code> shape ====

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

<pre class="jsonc">{
"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
]
}</pre>
Clients never write <code>message_history</code>. It is read-only on the API and rebuilt server-side on each edit (see <code>NoteMessageUpdateSpec</code> below).

== Resource specs (API schema) ==

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

=== Thread specs ===

{| class="wikitable"
|-
! Spec
! Role
! Fields exposed
! Notes
|-
| <code>NoteThreadSpec</code>
| shared base
| <code>id</code> (UUID, read), <code>title</code> (str, required, ≤255)
| <code>__model__ = NoteThread</code>; <code>__exclude__ = ["patient", "encounter"]</code>
|-
| <code>NoteThreadCreateSpec</code>
| write · create
| base + <code>encounter</code> (UUID, optional)
| Validates <code>encounter</code> exists (raises <code>Encounter not found</code>), then resolves the UUID to an <code>Encounter</code> FK in <code>perform_extra_deserialization</code>
|-
| <code>NoteThreadUpdateSpec</code>
| write · update
| base (<code>title</code>)
| No extra behaviour; <code>encounter</code> and <code>patient</code> cannot be reassigned through update
|-
| <code>NoteThreadReadSpec</code>
| read · detail/list
| base + <code>created_by</code>, <code>updated_by</code> (dict, nullable), <code>created_date</code>, <code>modified_date</code> (datetime)
| <code>perform_extra_serialization</code> sets <code>id = external_id</code> and serializes audit users via <code>serialize_audit_users</code>
|}

Validation and server behaviour:

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

=== Message specs ===

{| class="wikitable"
|-
! Spec
! Role
! Fields exposed
! Notes
|-
| <code>NoteMessageSpec</code>
| shared base
| <code>id</code> (UUID, read), <code>message</code> (str, required)
| <code>__model__ = NoteMessage</code>; <code>__exclude__ = ["thread"]</code>
|-
| <code>NoteMessageCreateSpec</code>
| write · create
| base (<code>message</code>)
| No extra behaviour
|-
| <code>NoteMessageUpdateSpec</code>
| write · update
| base (<code>message</code>)
| <code>perform_extra_deserialization</code> appends the pre-edit message to <code>message_history["history"]</code> (see below)
|-
| <code>NoteMessageReadSpec</code>
| read · detail/list
| base + <code>message_history</code> (dict), <code>created_by</code>, <code>updated_by</code> (dict, nullable), <code>created_date</code>, <code>modified_date</code> (datetime)
| <code>perform_extra_serialization</code> sets <code>id = external_id</code> and serializes audit users
|}

Validation and server behaviour:

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

== Methods & save behaviour ==

* <code>NoteThread</code> and <code>NoteMessage</code> inherit save and audit behaviour from [[References/Base models & conventions|<code>EMRBaseModel</code>]]: <code>external_id</code>, <code>created_by</code>/<code>updated_by</code>, <code>created_date</code>/<code>modified_date</code>, and soft delete via <code>deleted</code>.
* Read specs populate audit users through <code>EMRResource.serialize_audit_users</code>, which resolves <code>created_by</code>/<code>updated_by</code> to cached <code>UserSpec</code> dicts.
* <code>message_history</code> changes only inside <code>NoteMessageUpdateSpec.perform_extra_deserialization</code> — 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.

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

{{Related}}

References/Notes - Revision history

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

Admin: OHC identity seed