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

2026-07-06T04:17:49Z

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

← Older revision		Revision as of 09:47, 6 July 2026
Line 267:		Line 267:
	* <code>tags</code> on <code>RequestOrder</code> is an integer array of tag IDs, rendered to tag objects on read by the facility tag manager.		* <code>tags</code> on <code>RequestOrder</code> is an integer array of tag IDs, rendered to tag objects on read by the facility tag manager.
	* <code>external_id</code> (from <code>EMRBaseModel</code>) is the stable public identifier in API URLs — never the internal primary key.		* <code>external_id</code> (from <code>EMRBaseModel</code>) is the stable public identifier in API URLs — never the internal primary key.

			{{Navbox supply}}

	{{Related}}		{{Related}}

Admin: OHC identity seed

2026-07-04T22:45:51Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=supply
|title=Supply Request
|order=4
|introduced=3.0
|model=SupplyRequest
|reference=References/Base models & conventions
}}

A <code>SupplyRequest</code> is a single line item: a quantity of one catalogue item (<code>ProductKnowledge</code>) that someone wants moved. Requests never stand alone — each belongs to a <code>RequestOrder</code> that groups them and describes the movement into a destination facility location, optionally from a supplier organization and/or an origin location. You create requests when an order needs stock; you read them back as part of the order they hang off.

The Django model is only storage. <code>status</code>, <code>priority</code>, <code>intent</code>, <code>reason</code>, <code>category</code>, and <code>supplied_item_condition</code> are plain <code>CharField</code>s with no DB-level constraint, so the database will hold any string. The allowed values, validation, and request/response shapes live in the Pydantic resource specs under <code>care/emr/resources/inventory/supply_request/</code>, covered below.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/supply_request.py <code>care/emr/models/supply_request.py</code>]
* Spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/inventory/supply_request/spec.py <code>care/emr/resources/inventory/supply_request/spec.py</code>]
* Spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/inventory/supply_request/request_order.py <code>care/emr/resources/inventory/supply_request/request_order.py</code>]

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>SupplyRequest</code>
| A request for a quantity of a catalogue item (product knowledge), grouped under an order
|-
| <code>RequestOrder</code>
| An order that groups supply requests for movement of items into a destination facility location
|}

Both extend [[References/Base models & conventions|<code>EMRBaseModel</code>]], the shared Care EMR base providing <code>external_id</code>, audit fields (<code>created_date</code>/<code>modified_date</code>/<code>created_by</code>/<code>updated_by</code>), soft-delete via <code>deleted</code>, and <code>history</code>/<code>meta</code> JSON.

== <code>SupplyRequest</code> fields ==

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=SupplyRequest|section=SupplyRequest fields|name=status|type=CharField(255)|notes=Lifecycle status, spec-bound to <code>SupplyRequestStatusOptions</code> (see below). Required on write.}}
{{Field|model=SupplyRequest|section=SupplyRequest fields|name=quantity|type=DecimalField|notes=<code>max_digits=20</code>, <code>decimal_places=6</code>, nullable in DB. The write spec accepts a <code>Decimal</code> capped to <code>decimal_places=0</code> (whole numbers); the read spec returns it as an <code>int</code>.}}
{{Field|model=SupplyRequest|section=SupplyRequest fields|name=supplied_item_condition|type=CharField(255)|notes=Model-only — no current spec reads or writes it, so it's unreachable through the API.}}
{{Field|model=SupplyRequest|section=SupplyRequest fields|name=item|type=FK → ProductKnowledge|notes=<code>CASCADE</code>. The catalogue item being requested. Required on create, resolved server-side from an <code>external_id</code>. Cannot be changed afterwards.}}
{{Field|model=SupplyRequest|section=SupplyRequest fields|name=order|type=FK → RequestOrder|notes=<code>CASCADE</code>, nullable in DB but required by the spec on both create and update. Resolved server-side from an <code>external_id</code>.}}
|}

=== <code>SupplyRequestStatusOptions</code> values ===

Defined in <code>spec.py</code> and bound to <code>SupplyRequest.status</code>.

{| class="wikitable"
|-
! Value
|-
| <code>draft</code>
|-
| <code>active</code>
|-
| <code>suspended</code>
|-
| <code>cancelled</code>
|-
| <code>processed</code>
|-
| <code>completed</code>
|-
| <code>entered_in_error</code>
|}

== Related models ==

=== <code>RequestOrder</code> ===

The order is the unit you actually work with. It collects one or more <code>SupplyRequest</code> rows and carries the routing: a required <code>destination</code> facility location, plus an optional <code>supplier</code> organization and <code>origin</code> location.

<syntaxhighlight lang="text">supplier → FK Organization (nullable, CASCADE)
origin → FK FacilityLocation (nullable, CASCADE, related_name="origin_request_orders")
destination → FK FacilityLocation (CASCADE, related_name="destination_request_orders")</syntaxhighlight>
{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=SupplyRequest|section=RequestOrder|name=name|type=CharField(255)|notes=Required.}}
{{Field|model=SupplyRequest|section=RequestOrder|name=status|type=CharField(255)|notes=Spec-bound to <code>SupplyRequestOrderStatusOptions</code>.}}
{{Field|model=SupplyRequest|section=RequestOrder|name=note|type=TextField|notes=Optional (<code>str | None</code>).}}
{{Field|model=SupplyRequest|section=RequestOrder|name=tags|type=ArrayField[int]|notes=Default <code>list</code>; tag IDs, not a relational join. Expanded to tag objects on read via <code>SingleFacilityTagManager</code>.}}
{{Field|model=SupplyRequest|section=RequestOrder|name=priority|type=CharField(255)|notes=Spec-bound to <code>SupplyRequestPriorityOptions</code>.}}
{{Field|model=SupplyRequest|section=RequestOrder|name=intent|type=CharField(255)|notes=Spec-bound to <code>SupplyRequestIntentOptions</code>.}}
{{Field|model=SupplyRequest|section=RequestOrder|name=reason|type=CharField(255)|notes=Spec-bound to <code>SupplyRequestReason</code>.}}
{{Field|model=SupplyRequest|section=RequestOrder|name=category|type=CharField(255)|notes=Spec-bound to <code>SupplyRequestCategoryOptions</code>.}}
{{Field|model=SupplyRequest|section=RequestOrder|name=supplier|type=FK → Organization|notes=Nullable <code>CASCADE</code>. On write, must be an organization with <code>org_type == "product_supplier"</code> — the server rejects anything else.}}
{{Field|model=SupplyRequest|section=RequestOrder|name=origin|type=FK → FacilityLocation|notes=Nullable <code>CASCADE</code>, <code>related_name="origin_request_orders"</code>. The sending location.}}
{{Field|model=SupplyRequest|section=RequestOrder|name=destination|type=FK → FacilityLocation|notes=<code>CASCADE</code>, <code>related_name="destination_request_orders"</code>. The receiving location. Required.}}
|}

<code>origin</code> and <code>destination</code> both point at <code>FacilityLocation</code> but carry distinct <code>related_name</code>s, so one location can list the orders it sends (<code>origin_request_orders</code>) separately from the orders it receives (<code>destination_request_orders</code>).

=== <code>RequestOrder</code> enum values ===

From <code>request_order.py</code>. Each binds to the matching <code>RequestOrder</code> <code>CharField</code>.

==== <code>SupplyRequestOrderStatusOptions</code> (→ <code>status</code>) ====

{| class="wikitable"
|-
! Value
|-
| <code>draft</code>
|-
| <code>pending</code>
|-
| <code>in_progress</code>
|-
| <code>completed</code>
|-
| <code>abandoned</code>
|-
| <code>entered_in_error</code>
|}

<code>SUPPLY_REQUEST_ORDER_COMPLETED_STATUSES</code> = <code>[abandoned, entered_in_error, completed]</code> marks the terminal/closed statuses.

==== <code>SupplyRequestIntentOptions</code> (→ <code>intent</code>) ====

{| class="wikitable"
|-
! Value
|-
| <code>proposal</code>
|-
| <code>plan</code>
|-
| <code>directive</code>
|-
| <code>order</code>
|-
| <code>original_order</code>
|-
| <code>reflex_order</code>
|-
| <code>filler_order</code>
|-
| <code>instance_order</code>
|}

==== <code>SupplyRequestCategoryOptions</code> (→ <code>category</code>) ====

{| class="wikitable"
|-
! Value
|-
| <code>central</code>
|-
| <code>nonstock</code>
|}

==== <code>SupplyRequestPriorityOptions</code> (→ <code>priority</code>) ====

{| class="wikitable"
|-
! Value
|-
| <code>routine</code>
|-
| <code>urgent</code>
|-
| <code>asap</code>
|-
| <code>stat</code>
|}

==== <code>SupplyRequestReason</code> (→ <code>reason</code>) ====

{| class="wikitable"
|-
! Value
|-
| <code>patient_care</code>
|-
| <code>ward_stock</code>
|}

== Resource specs (API schema) ==

Every spec extends [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/base.py <code>EMRResource</code>] (<code>serialize</code> / <code>de_serialize</code>, with <code>perform_extra_serialization</code> / <code>perform_extra_deserialization</code> hooks). Write specs resolve foreign keys from <code>external_id</code> values in <code>perform_extra_deserialization</code>; read specs expand related objects in <code>perform_extra_serialization</code>.

=== Supply request specs (<code>spec.py</code>) ===

{| class="wikitable"
|-
! Spec class
! Role
! Fields
! Notes
|-
| <code>BaseSupplyRequestSpec</code>
| shared
| <code>id</code>, <code>status</code>, <code>quantity</code>
| <code>__model__ = SupplyRequest</code>, <code>__exclude__ = ["item"]</code>. <code>quantity: Decimal(max_digits=20, decimal_places=0)</code>. <code>status: SupplyRequestStatusOptions</code>.
|-
| <code>SupplyRequestWriteSpec</code>
| write · create
| base + <code>item: UUID4</code>, <code>order: UUID4</code>
| Resolves <code>item</code> → <code>ProductKnowledge</code> and <code>order</code> → <code>RequestOrder</code> by <code>external_id</code>; 404 if either is missing.
|-
| <code>SupplyRequestUpdateSpec</code>
| write · update
| base + <code>order: UUID4</code>
| Resolves <code>order</code> → <code>RequestOrder</code> by <code>external_id</code>. Omits <code>item</code> — the catalogue item is fixed once created.
|-
| <code>SupplyRequestReadSpec</code>
| read · detail/list
| base + <code>quantity: int</code>, <code>item: dict</code>, <code>order: dict</code>
| <code>id</code> = <code>external_id</code>. <code>item</code> expanded via <code>ProductKnowledgeReadSpec</code>; <code>order</code> via <code>SupplyRequestOrderReadSpec</code>.
|}

=== Request order specs (<code>request_order.py</code>) ===

{| class="wikitable"
|-
! Spec class
! Role
! Fields
! Notes
|-
| <code>BaseSupplyRequestOrderSpec</code>
| shared
| <code>id</code>, <code>status</code>, <code>name</code>, <code>note</code>, <code>intent</code>, <code>category</code>, <code>priority</code>, <code>reason</code>
| <code>__model__ = RequestOrder</code>. Coded fields bound to their enums; <code>note</code> optional.
|-
| <code>SupplyRequestOrderWriteSpec</code>
| write · create/update
| base + <code>supplier: UUID4 | None</code>, <code>origin: UUID4 | None</code>, <code>destination: UUID4</code>
| Resolves <code>supplier</code>/<code>origin</code>/<code>destination</code> by <code>external_id</code>. Raises <code>ValidationError</code> unless <code>supplier.org_type == "product_supplier"</code>.
|-
| <code>SupplyRequestOrderReadSpec</code>
| read · detail/list
| base + <code>supplier</code>, <code>origin: dict | None</code>, <code>destination: dict</code>, <code>tags: list[dict]</code>, <code>created_date</code>, <code>modified_date</code>, <code>created_by</code>, <code>updated_by</code>
| <code>id</code> = <code>external_id</code>. <code>supplier</code> expanded via <code>OrganizationReadSpec</code>; <code>origin</code>/<code>destination</code> via <code>FacilityLocationListSpec</code>; <code>tags</code> via <code>SingleFacilityTagManager</code>; audit users via <code>serialize_audit_users</code>.
|}

=== Validation and server-maintained behaviour ===

* '''FK resolution.''' Every foreign key on write comes in as an <code>external_id</code> UUID and is resolved server-side with <code>get_object_or_404</code>: <code>item</code>, <code>order</code>, <code>supplier</code>, <code>origin</code>, <code>destination</code>.
* '''Supplier type guard.''' <code>SupplyRequestOrderWriteSpec</code> rejects any <code>supplier</code> whose <code>org_type</code> is not <code>product_supplier</code>.
* '''<code>id</code> handling.''' Read specs set <code>id</code> to <code>external_id</code>; <code>de_serialize</code> never writes <code>id</code> or <code>external_id</code> back to the row.
* '''<code>quantity</code>.''' Write accepts a <code>Decimal</code> pinned to <code>decimal_places=0</code> (whole numbers) even though the DB column allows <code>decimal_places=6</code>; read returns an <code>int</code>.
* '''<code>item</code> immutability.''' Create takes <code>item</code>; <code>SupplyRequestUpdateSpec</code> drops it, so the requested catalogue item can't change after creation.

== Methods and save behaviour ==

* Neither model overrides <code>save()</code>; standard <code>EMRBaseModel</code> audit and soft-delete behaviour applies.
* Status is free-text at the DB layer — the lifecycle is enforced only by the spec enums at the API boundary. Neither model tracks <code>status_history</code>.
* Deleting a <code>RequestOrder</code> cascades to its <code>SupplyRequest</code> rows (the <code>order</code> FK is <code>CASCADE</code>); deleting a referenced <code>ProductKnowledge</code> cascades to the request.

== API integration notes ==

* Payload field names match the spec fields above. Foreign keys go out as <code>external_id</code> UUIDs on write and come back as expanded objects on read.
* Send <code>status</code>, <code>priority</code>, <code>intent</code>, <code>reason</code>, and <code>category</code> as the exact strings listed above — they're validated against the spec enums.
* <code>supplied_item_condition</code> lives on the model but no current spec surfaces it.
* <code>quantity</code> travels as a whole number through the specs; the DB column keeps six decimal places regardless.
* <code>tags</code> on <code>RequestOrder</code> is an integer array of tag IDs, rendered to tag objects on read by the facility tag manager.
* <code>external_id</code> (from <code>EMRBaseModel</code>) is the stable public identifier in API URLs — never the internal primary key.

{{Related}}

References/Supply Request - Revision history

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

Admin: OHC identity seed