Design within Orders

Owned by Chongsun Ahn (Unlicensed)
Last updated: Oct 28, 2016 by Josh Zamor

Proposed Design

Resource URL: /logisticsLocations/{locationId}/orders

An Order is a resource associated with a Logistics Location resource. This resource was modeled in v2 and previous using a Facility object. The change of Facility to Logistics Location is proposed based on the confusion of Facility in OpenLMIS having a broader definition than what is normally considered a facility (health facility, etc.). The term Logistics Location is generic and sufficient enough to solve the ambiguity.

Note, this does NOT mean that Logistics Location replaces Facility in OpenLMIS v3, only that in Order/Fulfillment and Stock Management contexts, the term Logistics Location is used, rather than Facility. For other parts of OpenLMIS, the Facility model will remain intact. There would also be some relationship between Facility and Logistics Location in the model.

Order Creation (POST)

An Order object would be POSTed to this endpoint, with the following attributes:

  • Requisition UUID (optional) - the requisition that is submitting this order (if there is one)
  • Requesting Logistics Location UUID (required) - the location that is submitting this order
  • Receiving Logistics Location UUID (optional) - the location that is receiving this order (if different from the requesting location). If this is not specified, the receiving location is the one that submitted the order.
  • Order Line Items (required) - the individual line items that comprise this order
  • Order Number (optional) - text to identify the order, not used by OpenLMIS for that purpose
  • Quoted Cost (optional) - quoted cost of the submitted order

Attributes of the Order Line Item object:

  • Global Product UUID (required/optional) - the global product identifier for the item. At least one must be specified. Open question about what to do if both are specified.
  • Trade Item UUID (required/optional) - the trade item identifier for the item. At least one must be specified. Open question about what to do if both are specified.
  • Quantity (required) - the quantity of the product (in packs)

Attributes of the Global Product object:

  • Short Name (required)
  • Long Name, Description (optional)
  • Unit (required) - called dispensing unit in v2, unit of issue in Logical Model.
  • Default Pack Size (required) - the number of dispensing units in a pack. Since this new Product Master model has two levels, Global Product and Trade Item, a pack size attribute is necessary for Global Product. This is just a default, as Trade Items associated with a Global Product may have multiple pack sizes defined.

Attributes of the Trade Item object:

  • Global Product UUID (optional) - the global product identifier. This is optional, as there may be a trade item in the system that has not been catalogued by the Logical Model.
  • Short Name (required)
  • Long Name, Description (optional)
  • Unit (required) - called dispensing unit in v2, unit of issue in Logical Model.
  • Pack Size (required) - the number of dispensing units in a pack.
  • GTIN (optional) - for GS1

Viewing Orders (GET)

The same URL is used. This shows all of the orders being fulfilled at this location. To view orders that have been requested at a location, a separate endpoint will provided.

Possible Design Changes

An alternate proposal to this design is to make the Global Product default pack size optional, and if it is not specified, the Order Line Item's quantity attribute would mean dispensing units, rather than packs. There are certain drawbacks to this design change.

  • It would introduce an idea of "range of estimate," rather than an "accurate estimate." An accurate estimate is more straightforward, "order 5 packs of 50 (pills)." But a range of estimate, "order 250 (pills)," may mean fulfilling with 3 packs, if packs only come in 100 pills. (This may not be a significant drawback.)
  • Pricing would be more complex, as orders would be done in dispensing units, but costs are not tracked by dispensing units, but by packs. (Costs per dispensing unit may be determined eventually, but not at order or fulfillment time.)

Open Questions

  • Can an Order Line Item have both Global Product and Trade Item specified? Are there scenarios where this makes sense? If so, the scenarios should inform the design proposal about what should be done if both are specified.

OpenLMIS: the global initiative for powerful LMIS software