Admin: Add Navbox platform (via update-page on MediaWiki MCP Server)

2026-07-06T04:23:55Z

Add Navbox platform (via update-page on MediaWiki MCP Server)

← Older revision		Revision as of 09:53, 6 July 2026
Line 261:		Line 261:
	* <code>template_type</code> and <code>context</code> must form a compatible pair (same <code>associating_model</code>). The default <code>context</code> is <code>encounter_base</code>, so templates target encounters unless changed.		* <code>template_type</code> and <code>context</code> must form a compatible pair (same <code>associating_model</code>). The default <code>context</code> is <code>encounter_base</code>, so templates target encounters unless changed.
	* <code>Template.facility</code> is nullable: null means instance-wide (<code>i-</code> slug), set means facility-scoped (<code>f-</code> slug).		* <code>Template.facility</code> is nullable: null means instance-wide (<code>i-</code> slug), set means facility-scoped (<code>f-</code> slug).

			{{Navbox platform}}

	{{Related}}		{{Related}}

Admin: OHC identity seed

2026-07-04T22:45:32Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=platform
|title=Report & Templates
|order=3
|introduced=3.0
|model=Report&Templates
|reference=References/Base models & conventions
}}

A <code>Template</code> defines reusable report markup and render options; a <code>ReportUpload</code> is one generated file (PDF/HTML/etc.) produced from that template and linked to a subject resource. You author templates through the API; report uploads are created for you by the file-upload flow.

Two layers back this:

* '''Storage layer''' — the Django models (<code>care/emr/models/report/</code>). Several fields are opaque (<code>TextField</code>/<code>JSONField</code>); their real shape lives in the spec layer, not the model.
* '''API layer''' — the Pydantic resource specs (<code>care/emr/resources/report/</code>), built on [[References/Base models & conventions|<code>EMRResource</code>]]. These define the enums, validation, the structure of the JSON fields, and the read/write schemas the API exposes.

'''Source:'''

* Models: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/report/report_upload.py <code>report_upload.py</code>], [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/report/template.py <code>template.py</code>]
* Resource specs: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/report/report_upload/spec.py <code>report/report_upload/spec.py</code>], [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/report/template/spec.py <code>report/template/spec.py</code>]

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>ReportUpload</code>
| An uploaded, generated report file (PDF/HTML/etc.) produced from a <code>Template</code> and linked to a subject resource via <code>associating_id</code>
|-
| <code>Template</code>
| A facility-scoped (or instance-wide) reusable report definition (markup + render options) used to generate reports
|}

<code>ReportUpload</code> extends [[References/Base models & conventions|<code>EMRBaseModel</code>]], the shared Care EMR base providing <code>external_id</code>, <code>meta</code>/<code>history</code> JSON, audit FKs, and soft-delete semantics.

<code>Template</code> extends [[References/Base models & conventions|<code>SlugBaseModel</code>]], the facility-scoped slug variant (<code>FACILITY_SCOPED = True</code>, which adds <code>slug</code> handling on top of the EMR base). Slugs carry a prefix in storage: <code>f-<facility_external_id>-<slug></code> when facility-scoped, <code>i-<slug></code> when instance-wide (see [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/base.py <code>base.py</code>]).

== <code>ReportUpload</code> fields ==

=== Core ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Report&Templates|section=Core|name=template|type=FK → Template (PROTECT)|notes=Template the report was generated from. The template cannot be deleted while reports reference it}}
{{Field|model=Report&Templates|section=Core|name=name|type=CharField(2000)|notes=Display name of the report. Required in every spec}}
{{Field|model=Report&Templates|section=Core|name=internal_name|type=CharField(2000)|notes=Randomized storage key, auto-generated on save so the file name never leaks PII (see [[#methods--save-behaviour}}
{{Field|model=Report&Templates|section=Core|name=associating_id|type=CharField(100)|notes=Non-null. Free-form identifier linking the report to its subject resource (e.g. an encounter)}}
{{Field|model=Report&Templates|section=Core|name=upload_completed|type=BooleanField|notes=Default <code>False</code>. Flips to <code>True</code> once the file upload to storage finishes}}
{{Field|model=Report&Templates|section=Core|name=report_type|type=CharField(50)|notes=File/content type of the report; also exposed via the <code>file_type</code> property for <code>S3FilesManager</code>}}
|}

=== Archival ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Report&Templates|section=Archival|name=is_archived|type=BooleanField|notes=Default <code>False</code>}}
{{Field|model=Report&Templates|section=Archival|name=archive_reason|type=TextField|notes=Blank allowed}}
{{Field|model=Report&Templates|section=Archival|name=archived_datetime|type=DateTimeField|notes=Nullable; set when the report is archived}}
{{Field|model=Report&Templates|section=Archival|name=archived_by|type=FK → User (PROTECT)|notes=Nullable. <code>related_name="archived_reports"</code>}}
|}

=== Inherited / metadata ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Report&Templates|section=Inherited / metadata|name=meta|type=JSONField (default {})|notes=Inherited from <code>EMRBaseModel</code>. Holds <code>mime_type</code> (surfaced by specs as <code>mime_type</code>) and other free-form metadata}}
{{Field|model=Report&Templates|section=Inherited / metadata|name=history|type=JSONField (default {})|notes=Inherited audit history}}
{{Field|model=Report&Templates|section=Inherited / metadata|name=created_by / updated_by|type=FK → User (SET_NULL)|notes=Inherited audit FKs; serialized as <code>created_by</code>/<code>updated_by</code> <code>UserSpec</code>}}
|}

=== Storage ===

<code>ReportUpload</code> declares a class-level <code>files_manager = S3FilesManager(BucketType.REPORT)</code>. The file body lives in object storage (REPORT bucket), not the database — the model row holds only metadata and the <code>internal_name</code> storage key.

== <code>Template</code> fields ==

The Django model stores most config as plain strings plus an opaque <code>options</code> <code>JSONField</code>. The constraints live in the spec layer: it pins <code>status</code>, <code>default_format</code>, and the slug, and validates the structure and mutual compatibility of <code>template_type</code>, <code>context</code>, and <code>options</code>.

{| class="wikitable"
|-
! Field
! Type (model)
! Spec constraint
! Notes
{{Field|model=Report&Templates|section=Template fields|name=facility|type=FK → Facility (PROTECT, nullable)|notes=<code>UUID4 | None</code> (write)}}
{{Field|model=Report&Templates|section=Template fields|name=slug|type=CharField(255)|notes=written via <code>slug_value: SlugType</code>; read as <code>slug</code> + parsed <code>slug_config</code>}}
{{Field|model=Report&Templates|section=Template fields|name=name|type=CharField(255)|notes=<code>str</code>, required}}
{{Field|model=Report&Templates|section=Template fields|name=status|type=CharField(255)|notes=<code>TemplateStatusOptions</code> enum}}
{{Field|model=Report&Templates|section=Template fields|name=template_data|type=TextField|notes=<code>str</code>, required (write)}}
{{Field|model=Report&Templates|section=Template fields|name=template_type|type=CharField(255)|notes=<code>str</code>, validated against <code>ReportTypeRegistry</code>}}
{{Field|model=Report&Templates|section=Template fields|name=default_format|type=CharField(255)|notes=<code>TemplateFormatOptions</code> enum}}
{{Field|model=Report&Templates|section=Template fields|name=context|type=CharField(100) (default "encounter_base")|notes=<code>str</code>, validated against <code>DataPointRegistry</code>}}
{{Field|model=Report&Templates|section=Template fields|name=description|type=TextField (blank, default "")|notes=<code>str = ""</code>}}
{{Field|model=Report&Templates|section=Template fields|name=options|type=JSONField (default {})|notes=<code>dict = {}</code>, validated against the format generator's <code>options_model</code>}}
|}

=== <code>TemplateStatusOptions</code> values ===

<code>status</code> is bound to this enum (<code>care/emr/resources/report/template/spec.py</code>):

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>draft</code>
| Template being authored, not yet usable
|-
| <code>active</code>
| Published, usable for generating reports
|-
| <code>retired</code>
| Withdrawn from use
|}

=== <code>TemplateFormatOptions</code> values ===

<code>default_format</code> is bound to this enum:

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>pdf</code>
| Render to PDF (uses the PDF generator's <code>options_model</code>)
|-
| <code>html</code>
| Render to HTML (uses the HTML generator's <code>options_model</code>)
|}

=== <code>slug_config</code> shape (read) ===

On read, <code>TemplateReadSpec</code> parses the stored prefixed slug back into a <code>slug_config</code> dict:

<syntaxhighlight lang="text">slug_config (facility-scoped) → { facility: <facility_external_id>, slug_value: <slug> }
slug_config (instance-wide) → { slug_value: <slug> } # parsed from "i-<slug>"</syntaxhighlight>
== Resource specs (API schema) ==

All specs subclass [[References/Base models & conventions|<code>EMRResource</code>]]. Read runs <code>serialize()</code> → DB-field copy → <code>perform_extra_serialization()</code> hook. Write runs <code>de_serialize()</code> → DB-field copy → <code>perform_extra_deserialization()</code> hook.

=== <code>ReportUpload</code> specs (<code>report/report_upload/spec.py</code>) ===

{| class="wikitable"
|-
! Spec class
! Role
! Fields / behaviour
|-
| <code>ReportUploadBaseSpec</code>
| shared
| <code>id: UUID4 | None</code>, <code>name: str</code>
|-
| <code>ReportUploadListSpec</code>
| read · list
| Adds <code>template</code> (nested <code>TemplateReadSpec</code>), <code>report_type</code>, <code>associating_id</code>, <code>archived_by</code> (<code>UserSpec</code>), <code>archived_datetime</code>, <code>upload_completed</code>, <code>is_archived</code>, <code>archive_reason</code>, <code>created_date</code>, <code>extension</code>, <code>uploaded_by</code>, <code>mime_type</code>
|-
| <code>ReportUploadRetrieveSpec</code>
| read · detail
| Extends list spec; adds <code>signed_url</code>, <code>read_signed_url</code>, <code>internal_name</code>
|}

Server-maintained read behaviour (<code>perform_extra_serialization</code>):

* <code>id</code> ← <code>obj.external_id</code>.
* <code>extension</code> ← <code>obj.get_extension()</code> (dotted extension parsed from <code>internal_name</code>).
* <code>mime_type</code> ← <code>obj.meta["mime_type"]</code>.
* <code>template</code> ← serialized via <code>TemplateReadSpec</code> (full nested template object).
* <code>created_by</code> / <code>updated_by</code> populated from the user cache via <code>serialize_audit_users</code>.
* '''Signed URLs (retrieve only):''' a freshly created object (<code>_just_created</code>) gets a write/upload <code>signed_url</code> via <code>files_manager.signed_url(obj)</code>; any other read gets a <code>read_signed_url</code> via <code>files_manager.read_signed_url(obj)</code>. Exactly one is populated per response.

<blockquote><code>ReportUpload</code> has no <code>CreateSpec</code>/<code>UpdateSpec</code> in this module. Uploads come from the file-upload flow ([[References/File Upload]]), and the report metadata and <code>internal_name</code> are platform-maintained. See [[#methods--save-behaviour|save behaviour]].
</blockquote>
=== <code>Template</code> specs (<code>report/template/spec.py</code>) ===

{| class="wikitable"
|-
! Spec class
! Role
! Fields / behaviour
|-
| <code>TemplateBaseSpec</code>
| shared
| <code>id</code>, <code>name</code>, <code>status</code> (<code>TemplateStatusOptions</code>), <code>default_format</code> (<code>TemplateFormatOptions</code>), <code>description = ""</code>, <code>options = {}</code>. <code>__exclude__ = ["facility"]</code>
|-
| <code>TemplateCreateSpec</code>
| write · create
| Adds <code>facility: UUID4 | None</code>, <code>slug_value: SlugType</code>, <code>template_data: str</code>, <code>template_type: str</code>, <code>context: str</code>
|-
| <code>TemplateUpdateSpec</code>
| write · update
| Identical to <code>TemplateCreateSpec</code> (<code>pass</code> subclass)
|-
| <code>TemplateReadSpec</code>
| read · list
| Base fields + <code>slug_config: dict</code>, <code>slug: str</code>, <code>template_type: str</code>, <code>context: str</code> (no <code>template_data</code>)
|-
| <code>TemplateRetrieveSpec</code>
| read · detail
| Extends read spec; adds nested <code>facility</code> (<code>FacilityBareMinimumSpec</code>) and <code>template_data: str</code>
|}

Write-side validation and side effects (<code>TemplateCreateSpec</code>):

* <code>slug_value</code> — <code>SlugType</code>: 5–50 chars, pattern <code>^[a-zA-Z0-9][a-zA-Z0-9_-]*[a-zA-Z0-9]$</code>.
* <code>template_type</code> (<code>field_validator</code>) — non-empty and resolvable via <code>ReportTypeRegistry</code>, else <code>Invalid report type</code>.
* <code>context</code> (<code>field_validator</code>) — non-empty and resolvable via <code>DataPointRegistry</code>, else <code>Invalid Context type</code>.
* <code>validate_report_type_and_context</code> (<code>model_validator</code>, after):
** both <code>template_type</code> and <code>context</code> must resolve, else <code>Invalid report type or context</code>;
** their <code>associating_model</code> must match (<code>template_type.associating_model == context.__associating_model__</code>), else <code>Report Type and Context are not compatible</code>;
** <code>options</code> is validated against <code>GeneratorRegistry.get(default_format).options_model</code>, so the allowed <code>options</code> keys depend on whether <code>default_format</code> is <code>pdf</code> or <code>html</code>.
* <code>perform_extra_deserialization</code> (side effects): resolves <code>facility</code> external ID to the <code>Facility</code> row (<code>get_object_or_404</code>) when provided, and sets <code>obj.slug = self.slug_value</code> (the raw value; the model prefixes it in <code>calculate_slug</code>).

Read-side behaviour:

* <code>TemplateReadSpec.perform_extra_serialization</code>: <code>id ← external_id</code>; <code>slug_config ← obj.parse_slug(obj.slug)</code> (see [[#slug_config-shape-read|<code>slug_config</code> shape]]).
* <code>TemplateRetrieveSpec</code>: additionally serializes <code>facility</code> via <code>FacilityBareMinimumSpec</code> when set.

== Methods & save behaviour ==

=== <code>ReportUpload.save()</code> ===

On create (no <code>id</code>) or when <code>internal_name</code> is empty, <code>save()</code> generates a random <code>internal_name</code> from <code>uuid4()</code> plus the current epoch. This intermediate name decouples the stored object from the human-readable <code>name</code>, so a storage or data leak never exposes PII in file names.

* Pass <code>skip_internal_name=True</code> to <code>save()</code> to bypass generation and keep an explicitly set <code>internal_name</code>.
* If <code>internal_name</code> already held a value, its file extension is parsed (via <code>parse_file_extension</code>) and appended to the new randomized name.

=== <code>ReportUpload.get_extension()</code> ===

Returns the dotted extension(s) parsed from <code>internal_name</code> (e.g. <code>.pdf</code>), or <code>""</code> if none. Surfaced as the <code>extension</code> field in read specs.

=== <code>ReportUpload.file_type</code> (property) ===

Alias for <code>report_type</code>, kept for compatibility with <code>S3FilesManager</code>.

=== <code>Template</code> slug methods (inherited from <code>SlugBaseModel</code>) ===

* <code>calculate_slug()</code> — returns the prefixed slug: <code>f-<facility.external_id>-<slug></code> when facility-scoped, else <code>i-<slug></code>.
* <code>parse_slug(slug)</code> — the inverse; returns <code>slug_config</code> (used by <code>TemplateReadSpec</code>).

== API integration notes ==

* Report files live in object storage (S3-compatible REPORT bucket) and are read through <code>S3FilesManager</code>; the database row is metadata only.
* <code>internal_name</code> is platform-maintained — never set it from a client. Reserve <code>skip_internal_name</code> for controlled migrations. It is exposed only via <code>ReportUploadRetrieveSpec</code>.
* A freshly created report returns an upload <code>signed_url</code>; subsequent reads return a <code>read_signed_url</code> instead.
* Treat a report as available only once <code>upload_completed</code> is <code>True</code>.
* Populate <code>associating_id</code> when generating a report so the file can be retrieved in its subject resource's context.
* <code>Template.options</code> is validated server-side against the chosen format's generator schema, not an arbitrary bag; valid keys depend on <code>default_format</code> (<code>pdf</code>/<code>html</code>).
* <code>template_type</code> and <code>context</code> must form a compatible pair (same <code>associating_model</code>). The default <code>context</code> is <code>encounter_base</code>, so templates target encounters unless changed.
* <code>Template.facility</code> is nullable: null means instance-wide (<code>i-</code> slug), set means facility-scoped (<code>f-</code> slug).

{{Related}}

References/Report & Templates - Revision history

Admin: Add Navbox platform (via update-page on MediaWiki MCP Server)

Admin: OHC identity seed