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

2026-07-06T04:23:01Z

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

← Older revision		Revision as of 09:53, 6 July 2026
Line 313:		Line 313:
	* Archival (<code>POST .../{external_id}/archive/</code>, body <code>{ archive_reason }</code>) sets <code>is_archived</code>, <code>archive_reason</code>, <code>archived_datetime</code>, <code>archived_by</code> server-side and returns <code>FileUploadListSpec</code>. This soft state is separate from the <code>EMRBaseModel</code> soft-delete (<code>deleted</code>).		* Archival (<code>POST .../{external_id}/archive/</code>, body <code>{ archive_reason }</code>) sets <code>is_archived</code>, <code>archive_reason</code>, <code>archived_datetime</code>, <code>archived_by</code> server-side and returns <code>FileUploadListSpec</code>. This soft state is separate from the <code>EMRBaseModel</code> soft-delete (<code>deleted</code>).
	* <code>mark_upload_completed</code> and <code>archive</code> both return <code>FileUploadListSpec</code> (no signed URL).		* <code>mark_upload_completed</code> and <code>archive</code> both return <code>FileUploadListSpec</code> (no signed URL).

			{{Navbox platform}}

	{{Related}}		{{Related}}

Admin: OHC identity seed

2026-07-04T22:45:30Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=platform
|title=File Upload
|order=1
|introduced=3.0
|model=FileUpload
|reference=References/User & Skills
}}

A <code>FileUpload</code> is the metadata record for a file living in S3-compatible object storage. You touch it whenever a Care resource needs an attachment — a patient document, an X-ray on an encounter, a signed consent form.

Two layers split the work. The Django model is storage: it persists the row and an opaque <code>meta</code> JSON column, nothing more. The Pydantic resource specs in <code>care/emr/resources/file_upload/spec.py</code> are the API — they define the <code>file_type</code> / <code>file_category</code> enums, validate the upload, decide what goes into <code>meta</code> (<code>mime_type</code>), and shape every read/write payload, including <code>extension</code>, <code>signed_url</code>, and <code>read_signed_url</code>, which are computed on the fly and have no backing columns.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/file_upload.py <code>care/emr/models/file_upload.py</code>]
* Specs: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/file_upload/spec.py <code>care/emr/resources/file_upload/spec.py</code>]
* Viewset: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/api/viewsets/file_upload.py <code>care/emr/api/viewsets/file_upload.py</code>]

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>FileUpload</code>
| Metadata record for a file stored in object storage (S3), associated with another Care resource by <code>file_type</code> + <code>associating_id</code>
|}

<code>FileUpload</code> extends [[References/Base models & conventions|<code>EMRBaseModel</code>]] (shared Care EMR base with <code>external_id</code>, <code>meta</code> JSON, audit fields, and soft-delete semantics).

== <code>FileUpload</code> fields ==

=== File metadata ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=FileUpload|section=File metadata|name=name|type=CharField(2000)|notes=User-facing file name. Required on the API (<code>FileUploadBaseSpec.name</code>)}}
{{Field|model=FileUpload|section=File metadata|name=internal_name|type=CharField(2000)|notes=Storage object key. Set server-side from <code>original_name</code> on create, then a random key is generated on <code>save()</code>. Never set by clients}}
{{Field|model=FileUpload|section=File metadata|name=associating_id|type=CharField(100)|notes=The <code>external_id</code> of the owning resource. Required (<code>blank=False, null=False</code>). There's no DB <code>ForeignKey</code> — integrity is enforced in the app layer}}
{{Field|model=FileUpload|section=File metadata|name=file_type|type=CharField(100)|notes=Domain of the owning resource. API-constrained to [[#filetypechoices-values}}
{{Field|model=FileUpload|section=File metadata|name=file_category|type=CharField(100)|notes=API-constrained to [[#filecategorychoices-values}}
{{Field|model=FileUpload|section=File metadata|name=upload_completed|type=BooleanField|notes=Default <code>False</code>. Flips to <code>True</code> once the client finishes the direct-to-S3 upload — or immediately, on the inline <code>upload-file</code> path}}
|}

=== <code>meta</code> JSON contents ===

<code>meta</code> is the opaque <code>JSONField</code> inherited from <code>EMRBaseModel</code>. The specs put exactly one structured key in it:

{| class="wikitable"
|-
! Key
! Type
! Shape / Notes
|-
| <code>mime_type</code>
| <code>str</code>
| MIME type of the file. Written in <code>FileUploadCreateSpec.perform_extra_deserialization</code> (<code>obj.meta["mime_type"] = self.mime_type</code>); read back during serialization via <code>obj.meta.get("mime_type")</code>. Validated against <code>settings.ALLOWED_MIME_TYPES</code>
|}

=== Archival ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=FileUpload|section=Archival|name=is_archived|type=BooleanField|notes=Default <code>False</code>}}
{{Field|model=FileUpload|section=Archival|name=archive_reason|type=TextField|notes=Blank-able; set when archiving (required in the <code>archive</code> action body)}}
{{Field|model=FileUpload|section=Archival|name=archived_datetime|type=DateTimeField|notes=Nullable; set to <code>timezone.now()</code> when archived}}
{{Field|model=FileUpload|section=Archival|name=archived_by|type=FK → User (PROTECT)|notes=Nullable; <code>related_name="archived_files"</code>}}
|}

=== Storage manager ===

<code>FileUpload</code> declares a class-level <code>files_manager = S3FilesManager(BucketType.PATIENT)</code>. It's not a database field — it's the object-storage helper that mints signed write/read URLs and runs <code>put_object</code>, all against the <code>PATIENT</code> bucket.

== Enums ==

=== <code>FileTypeChoices</code> values ===

The owning-resource domain (<code>spec.py</code>). String enum.

{| class="wikitable"
|-
! Value
! Links a file to
|-
| <code>patient</code>
| A [[References/Patient
|-
| <code>encounter</code>
| An [[References/Encounter
|-
| <code>consent</code>
| A [[References/Consent
|-
| <code>diagnostic_report</code>
| A [[References/Diagnostic Report
|-
| <code>service_request</code>
| A [[References/Service Request
|}

=== <code>FileCategoryChoices</code> values ===

File category (<code>spec.py</code>). String enum.

{| class="wikitable"
|-
! Value
|-
| <code>audio</code>
|-
| <code>xray</code>
|-
| <code>identity_proof</code>
|-
| <code>unspecified</code>
|-
| <code>discharge_summary</code>
|-
| <code>consent_attachment</code>
|}

== Resource specs (API schema) ==

Every spec extends <code>EMRResource</code> (<code>care/emr/resources/base.py</code>), which supplies <code>serialize</code> (DB → Pydantic) and <code>de_serialize</code> (Pydantic → DB) plus the <code>perform_extra_serialization</code> / <code>perform_extra_deserialization</code> hooks. <code>FileUpload</code> deliberately omits <code>__store_metadata__</code>, so its hooks move <code>mime_type</code> in and out of <code>meta</code> by hand instead of leaning on the generic meta machinery.

{| class="wikitable"
|-
! Spec
! Role
! Exposes / behaviour
|-
| <code>FileUploadBaseSpec</code>
| shared base
| <code>id: UUID4 | None</code>, <code>name: str</code> (required)
|-
| <code>FileUploadCreateSpec</code>
| write · create
| Adds <code>original_name</code>, <code>file_type</code>, <code>file_category</code>, <code>associating_id</code>, <code>mime_type</code>. Validates <code>mime_type</code> and <code>original_name</code>; on deserialize sets <code>_just_created=True</code>, <code>internal_name = original_name</code>, and <code>meta["mime_type"]</code>
|-
| <code>FileUploadUpdateSpec</code>
| write · update
| Same fields as base (<code>id</code>, <code>name</code>) — the display name is the only thing you can edit
|-
| <code>FileUploadListSpec</code>
| read · list
| Read view (fields below); resolves <code>extension</code>, <code>mime_type</code>, audit users, <code>uploaded_by</code>, <code>archived_by</code>
|-
| <code>FileUploadRetrieveSpec</code>
| read · detail
| Extends <code>FileUploadListSpec</code> with <code>signed_url</code>, <code>read_signed_url</code>, <code>internal_name</code>; emits a write URL for just-created rows, otherwise a read URL
|-
| <code>ConsentFileUploadCreateSpec</code>
| write · create (consent)
| <code>original_name</code> + <code>associating_id: UUID4</code>; forces <code>file_type=consent</code>, <code>file_category=consent_attachment</code> server-side
|}

Nothing here binds to a value set or uses <code>CodeableConcept</code> / <code>Period</code> / other <code>common</code> types — <code>file_type</code> and <code>file_category</code> are plain string enums.

=== <code>FileUploadCreateSpec</code> validation ===

{| class="wikitable"
|-
! Field
! Rule
|-
| <code>name</code>
| Required (inherited from base)
|-
| <code>original_name</code>
| Non-empty; run through <code>file_name_validator</code> (<code>care/utils/models/validators.py</code>): ≤ 255 chars, must not start with <code>.</code>, must have an extension, extension must be in <code>ALLOWED_FILE_EXTENSIONS</code> and not in <code>BLOCKED_FILE_EXTENSIONS</code>
|-
| <code>mime_type</code>
| Must be in <code>settings.ALLOWED_MIME_TYPES</code>, else <code>"Invalid mime type"</code>
|-
| <code>file_type</code>
| Must be a <code>FileTypeChoices</code> member
|-
| <code>file_category</code>
| Must be a <code>FileCategoryChoices</code> member
|-
| <code>associating_id</code>
| Required <code>str</code>
|}

=== <code>FileUploadListSpec</code> read fields ===

{| class="wikitable"
|-
! Field
! Type
! Source
|-
| <code>id</code>
| <code>UUID4</code>
| <code>obj.external_id</code> (set in <code>perform_extra_serialization</code>)
|-
| <code>name</code>
| <code>str</code>
| column
|-
| <code>file_type</code>
| <code>FileTypeChoices</code>
| column
|-
| <code>file_category</code>
| <code>FileCategoryChoices</code>
| column
|-
| <code>associating_id</code>
| <code>str</code>
| column
|-
| <code>upload_completed</code>
| <code>bool</code>
| column
|-
| <code>is_archived</code>
| <code>bool | None</code>
| column
|-
| <code>archive_reason</code>
| <code>str | None</code>
| column
|-
| <code>archived_datetime</code>
| <code>datetime | None</code>
| column
|-
| <code>created_date</code>
| <code>datetime</code>
| column
|-
| <code>extension</code>
| <code>str</code>
| derived via <code>obj.get_extension()</code>
|-
| <code>mime_type</code>
| <code>str</code>
| <code>obj.meta.get("mime_type")</code>
|-
| <code>uploaded_by</code>
| <code>dict | None</code>
| <code>UserSpec</code> from cache (<code>obj.created_by_id</code>)
|-
| <code>archived_by</code>
| <code>UserSpec | None</code>
| <code>UserSpec</code> from cache (<code>obj.archived_by_id</code>)
|-
| <code>created_by</code> / <code>updated_by</code>
| <code>dict | None</code>
| <code>serialize_audit_users</code>
|}

=== <code>FileUploadRetrieveSpec</code> extra fields ===

{| class="wikitable"
|-
! Field
! Type
! When populated
|-
| <code>signed_url</code>
| <code>str | None</code>
| When <code>obj._just_created</code> is truthy — a write (PUT) URL from <code>files_manager.signed_url(obj)</code>. The upload target handed back at create time
|-
| <code>read_signed_url</code>
| <code>str | None</code>
| Otherwise — a read (GET) URL from <code>files_manager.read_signed_url(obj)</code>
|-
| <code>internal_name</code>
| <code>str</code>
| The storage object key (flagged in source as possibly not needing to be returned)
|}

== Methods & save behaviour ==

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

Derives the file extension from <code>internal_name</code> via <code>parse_file_extension</code>, formatted as <code>.ext</code> (or a multi-part form like <code>.tar.gz</code>), or <code>""</code> when there's none. This is what surfaces to clients as the <code>extension</code> read field.

=== <code>save()</code> side effects ===

On save, a random <code>internal_name</code> is generated when <code>internal_name</code> is empty or the row is new (<code>not self.id</code>) and the caller has not passed <code>skip_internal_name=True</code>:

# A random <code>internal_name</code> is generated as <code>uuid4() + int(time.time())</code>.
# If an extension can be derived, it is appended to that random name.
# <code>internal_name</code> is set before the row is persisted.

Keeping the user-supplied <code>name</code> out of the storage key limits PII leakage if the bucket is compromised. The inline <code>upload-file</code> path calls <code>save(skip_internal_name=True)</code> after uploading, so the generated key survives.

== API integration notes ==

=== Two upload flows ===

# '''Signed-URL (direct-to-S3), default:''' <code>POST</code> a <code>FileUploadCreateSpec</code>. The server validates, deserializes (<code>_just_created=True</code>), and returns <code>FileUploadRetrieveSpec</code> carrying a write <code>signed_url</code>. The client <code>PUT</code>s the bytes straight to S3, then calls <code>POST .../{external_id}/mark_upload_completed/</code> to flip <code>upload_completed=True</code>.
# '''Inline base64 (<code>POST .../upload-file/</code>):''' the client sends <code>original_name</code> + base64 <code>file_data</code>. The server decodes it, enforces <code>settings.MAX_FILE_UPLOAD_SIZE</code> (MB), sniffs the real MIME type with <code>python-magic</code>, re-checks <code>ALLOWED_MIME_TYPES</code>, builds a <code>FileUploadCreateSpec</code>, sets <code>_just_created=False</code>, uploads via <code>files_manager.put_object</code>, sets <code>upload_completed=True</code>, and returns <code>FileUploadRetrieveSpec</code> — so the response carries <code>read_signed_url</code>, not a write URL.

=== Server-maintained behaviour ===

* <code>internal_name</code> is platform-maintained — never set it from a client; the model generates a random PII-free key.
* <code>mime_type</code> lives in <code>meta</code>, not a column. <code>FileUploadCreateSpec</code> writes it and serialization reads it back. On the inline path it is re-derived from file content (<code>magic.from_buffer</code>) rather than trusted from the client.
* <code>associating_id</code> + <code>file_type</code> together link a file to its owning resource. <code>list</code> requires both as query params and returns only <code>upload_completed=True</code> rows.
* Every action runs <code>file_authorizer(user, file_type, associating_id, "read"|"write")</code>.
* Archival (<code>POST .../{external_id}/archive/</code>, body <code>{ archive_reason }</code>) sets <code>is_archived</code>, <code>archive_reason</code>, <code>archived_datetime</code>, <code>archived_by</code> server-side and returns <code>FileUploadListSpec</code>. This soft state is separate from the <code>EMRBaseModel</code> soft-delete (<code>deleted</code>).
* <code>mark_upload_completed</code> and <code>archive</code> both return <code>FileUploadListSpec</code> (no signed URL).

{{Related}}

References/File Upload - Revision history

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

Admin: OHC identity seed