Updated for OpenLMIS 3.0. See previous versions of this page and Beta to 3.0 changes for historical information.

See Product Identification Terminology Reference for updated terminology around Products, their identification, classification and related concepts.

Introduction

OpenLMIS provides functionality for medical commodity logistics: ordering, shipping, receiving, and managing stock. In OpenLMIS 3.0, the model for storing and managing this data has been redesigned to align with the global GS1 standards. This new model has benefited from significant feedback and collaboration with representatives of GS1, USAID, BI&A LRM (Intellicog - Logical Reference Model).

This page documents the model as it exists in OpenLMIS 3.0; whereas the wiki sub-pages outline the direction of future development and should be considered working designs.

Our goal is to put the OpenLMIS community and code-base a step ahead in implementing best practices. This will provide long-term benefits including global alignment around analytics, end-to-end visibility, and shared value as the global community works to improve medical supply chains in an increasing number of countries.

Data Model

Modeling of medical commodities is central to OpenLMIS. Correctly modeling commodities enables administrators to:

set up forms for requisitioning and re-supply
managing their stock in inventory
assess what their budget may support
provide full visibility into a working supply chain
enable trace-ability from production to consumption

Table of Contents

Orderables

In OpenLMIS 3.0 we represent medical commodities with the Orderable domain object, called "Product" in previous versions. The term "Product" is no longer used in OpenLMIS because it means many different things to different stakeholders. The term Orderable emphasizes the abstract notion of some commodity that may be ordered.

An Orderable represents any item that may be ordered. For example, an item may be ordered on a Requisition form by a storeroom manager in a medical facility. An Orderable in OpenLMIS 3.0 must be connected to either a TradeItem (a specific item by a manufacturer/brand owner) or to a CommodityType (one category of medicines or commodities). Each of those is described further below.

An Orderable is identified uniquely within an implementation by its Product Code. A Product Code is an implementation specific identifier that can be used to assist people in filling out paper forms, as well as, external systems so that each system references the same commodity code to support accurate ordering. Orderable's may also answer a number of questions that typically arise when one needs to order them:

how many patients may I dispense to if I order one?
what Programs may I order this through? and what does that Program stipulate about ordering this?
what other commodities may also be used to fulfill the given Orderable if it is out of stock?

Trade Items

A TradeItem in OpenLMIS follows the GS1 concept and is, as the name implies, an item meant for trade. These are most often items that have a specific manufacturer or brand owner and are typically identified and defined by that manufacturer or brand owner outside of OpenLMIS. A TradeItem can have an associated GS1 GTIN (Global Trade Item Number) if GTINs are being used. OpenLMIS can provide basic GTIN check digit validation.

Every Orderable can be connected to one TradeItem (or, alternatively, it could be connected to a CommodityType, described below). We refer to this as a TradeItem's Orderable. With this kind of Orderable, an end-user is ordering a specific, real item. A TradeItem should only have at most one Orderable in OpenLMIS. That gives it a single product code by which it is known in that entire OpenLMIS implementation. A TradeItem Orderable can have different settings that vary for different Programs; more on Programs below.

When a TradeItem's Orderable appears on an order form (a Requisition form), it means the end-user is ordering a specific (likely manufactured) item. For example, an end-user may order 10 units of an Orderable, and its TradeItem may be used to fulfill that order. TradeItems may have a GTIN and are the only concept that may have Lots/Batches or serial numbers. Tracking expiration dates or handling product recalls are made possible by tracking these Trade Item attributes end-to-end through the supply chain. Furthermore, each location where the stock of that item is ordered, warehoused, delivered and stored can be associated with a GS1 GLN (Global Location Number).

Commodity Types

CommodityTypes represent classifications of commodities. These may be hierarchical or may be flat. Widely-used examples include UNSPSC and GPC. Multiple classification systems can be in use at the same time in a single OpenLMIS implementation. The ability to handle hierarchy and branching follows GS1 best practice and allows an implementation to mix and match existing classification systems in practice. For these reasons, each TradeItem may be tied to one CommodityType in each classification system (e.g., one in UNSPSC and one in GPC).

A Orderable can be constructed from one Commodity Type (or, alternatively, it could be connected to a TradeItem, as above). We refer to this as CommodityType's Orderable. With this kind of Orderable, an end-user is ordering a classification of commodities. A CommodityType's Orderable is the more typical kind used in OpenLMIS. That is typical because often an end-user does not need to order a specific manufacturer's Trade Item (Advil Extra Strength 100mg), but instead wants to order a classification (Ibuprofen 100mg). Later, when a requisition becomes an actual shipment and delivery, some tangible item—a real TradeItem like Advil Extra Strength—can fulfill that order. That is allowed as long as the TradeItem is compatible with the CommodityType (see more about Fulfillment below).

Programs

OpenLMIS can handle multiple Programs operating at once. Each Program has a specific set of Orderables, a complex configuration including Requisition Form settings and Program-specific user permissions, and a network of Facilities that are participating in the Program. For example, a Malaria program may be operating in a country in parallel with a Family Planning program. The Malaria and Family Planning programs may have their own sets of Orderables, users, warehouses, clinic facilities, and configurations.

Sometimes TradeItems and Orderables may overlap between Programs. A specific medicine may be provided by two different programs backed by two different funders and/or supply chains. Even thought it is the same TradeItem, it may have a different configuration in each program. Perhaps a different cost to account for or a different hierarchy of approvals, for example.

Display Categories

An OrderableDisplayCategory provides a name and display order for a given Orderable applied to a Program. This allows Orderable items to be grouped into categories within the OpenLMIS user interface, such as on a requisition order form. This grouping does not need to match any of the CommodityTypes categories or any official classifications such as UNSPSC. OrderableDisplayCategories provide complete freedom to configure whatever groupings make sense for any given Program. In most cases though it's assumed that an implementation following a well-sourced classification system could simply use that Classification System for its OrderableDisplayCategories.

Example Scenario: Malaria

In this scenario, we consider the Malaria drug Mefloquine. Mefloquine is a CommodityType in OpenLMIS. It is categorized as follows within the UNSPSC classification system:

Drugs and Pharmaceutical Products (51100000)
→ Antiprotozoals (51101900)
→ Mefloquine (51101902)

UNSPSC is a globally-used classification system; see more about GS1 Product Categorization. In OpenLMIS, the UNSPSC hierarchy is represented as CommodityTypes that capture all the pieces of that hierarchy in use.

Altimef and Confal are two manufacturer brand names for Mefloquine (source). These are represented as two distinct TradeItems in OpenLMIS, both which list themselves as in the Mefloquine CommodityType in the UNSPSC classification system. Each one may have a distinct GS1 GTIN. As these specific trade items are shipped, delivered, stocked and utilized, the Lots/Batches, serial numbers and GLNs can be used to track where specific items are located in the supply chain and at service delivery points (like a specific health clinic).

Orderable items are set up in OpenLMIS to represent the ability to order these drugs. In this scenario, 4 different Orderable records would be established as follows:

2 TradeItem Orderable records, one tied to TradeItem Altimef and the other tied to TradeItem Confal.
2 CommodityType Orderable records, both tied to the Mefloquine CommodityType, but one with a Dispensable that matches Altimef and the other with a Dispensable that matches Confal.

The Orderable records would include their OpenLMIS product code, the Dispensable details, the number of dispensing units in each pack, etc. We'll say that Altimef comes in individual pills of 100mg, and Confal comes in strips of 2 pills of 25mg. In the future, many of these attributes could be pulled directly from the TradeItem information through a GS1 GDSN using the respective GTINs.

The CommodityType Orderables would likely be used on a requisition form to allow users to order Mefloquine with each kind of dispensing unit. Later in the supply chain when a specific Trade Item is shipped and delivered, the Altimef and Confal TradeItem records would be connected. This would allow the connection to additional GS1 data such as Lots/Batches and more.

How Items Fulfill for Orders

An Orderable item in OpenLMIS may be associated with a CommodityType (like UNSPSC Mefloquine) or may be associated with a TradeItem (like Altimef). When an order is placed, or when stock is managed, specific items may fulfill for that order.

To create a fulfillable relationship between Altimef and Confal with Mefloquine we would need the connections described in the scenario above. Namely:

Specific TradeItems (like Altimef and Confal) associated with a CommodityType (like UNSPSC Mefloquine).
TradeItem Orderables for each TradeItem.
CommodityType Orderables, one for each different Dispensing unit to match the TradeItems.

Specifically, here are the conditions under which OpenLMIS allows fulfillment:

A TradeItem may fulfill for a CommodityType if:
- the TradeItem is classified by the CommodityType.
- AND the CommodityType has an Orderable which has an equivalent Dispensible as the Orderable which the TradeItem has.

That setup allows orders to be placed for a CommodityType but later fulfilled by a specific TradeItem.

Basic Example: Same Medicine from Different Manufacturers

In some situations, a medical commodity is made by two or more manufacturers, each with the same dispensing units. For example, Ibuprofen is a widely-used pain reliever available in 200mg tablets. In the United States, these 200mg tablets are available under many brand names such as Advil and Motrin. The dispensing units are identical, and a facility that orders Ibuprofen might not care which brand name they receive.

In OpenLMIS, this scenario would be addressed by using a CommodityType Orderable for Ibuprofen. Each of the manufacturers' products would be entered as its own Trade Item record (with its own GTIN it may be sourced from a GDSN provider) that each have their own Orderable. All these records would have matching Dispensing Unit information from their Orderable. This would allow facilities to order Ibuprofen and allow the logistics staff to fulfill that order with either Advil or Motrin.

A storeroom manager at a facility will see a list of Orderable items on their requisition form.

Orderables

Ibuprofen Commodity Type Orderable

- product code: P1
- name: Ibuprofen
- Dispensable: 200mb tablet
- also has net content (aka packSize) and other properties
- belongs to a Ibuprofen Commodity Type
- connection to Program and approved commodity list allows the facility to Requisition it
- information such as estimated price may be looked up

This Commodity Type defines the classification system:

Commodity Types

Ibuprofen

- - name: Ibuprofen
  - classificationSystem: UNSPSC
  - classificationId: 51384509
  - may have a parent category (51384500)

Next, a warehouse clerk will fulfill the order by identifying the Trade Items including GTINs, Lot information, and quantities to ship. This may be done by identifying all the trade items in stock which list themselves as Commodity Type Ibuprofen (UNSPSC 5138409).

Trade Items

Advil

- - gtin: 305730154758
  - manufacturer: Pfizer Consumer Healthcare
  - for UNSPSC in Commodity Type 'Ibuprofen' (51384509)
  - may have data about Lots

Motrin

- - gtin: 300450481528
  - manufacturer: McNeil Consumer Healthcare
  - for UNSPSC in Commodity Type 'Ibuprofen' (51384509)
  - may have data about Lots

Finally, a central logistician can run a report on the commodity types to understand consumption levels. In addition, if a certain Trade Item is recalled, a central logistician can run a report to identify which Lots of recalled Trade Items were shipped to which facilities.

Whether to Requisition Based on Trade Items or Commodity Types

In OpenLMIS, either a specific Trade Item or a broad Commodity Type can be configured as an Orderable item to appear on a Requisition form.

There are pros and cons for each:

	Pros	Cons
Commodity Types	Allows staff to order medicines without knowing which specific Trade Item will be provided. This allows fulfillment staff the most flexibility to fulfill an order with the most appropriate Trade Items based on availability, pack sizes, and shipping considerations.	Provides less visibility at ordering time into the different pack sizes or different product costs.
Trade Items	This means that a product code for each Trade Item allows staff at authorized facilities to specifically order that specific Trade Item. Allows staff to see and choose manufacturer-specific information while placing an order, such as pack sizes or brand-specific costs.	Provides less flexibility during fulfillment to substitute one Trade Item for another*. Is more burdensome to configure for large implementations.

*Having one Trade Item fulfill for the other is not currently supported in v3.0. In the future we plan to support this; see "How one Trade Item fulfills for another" section below.

Regardless of which configuration you are using, OpenLMIS can still contain Trade Item records (with GTINs) and Lot information that can be tracked during Fulfillment. In other words, even if you choose to Requisition based on Commodity Types, during the Fulfillment process the exact Trade Items that are shipped can be tracked, ideally with GS1 identifiers.

Advanced Example: Same Medicine with Different Pack Size

A different situation is when the same medicine in the same dispensing units comes from different manufacturers with different package sizes. An example of this is Quinine Sulphate, used to treat malaria. The dispensing unit given to a patient is a 300mg capsule. This drug is made by two manufacturers, Elys Chemical Industries Ltd. in Kenya and Actavis in the U.K. Actavis has a GTIN for their trade item (5012617009999) while Elys does not.

Both trade items have the same Dispensable, a 300mg capsule. However, Actavis distributes their product in packs of 100 capsules, while Elys provides packs of 1,000 capsules.

This could be handled in OpenLMIS in multiple ways, each with pros and cons for how orders can be fulfilled:

Configuration

Explanation

Pros

Cons

Requisition based on 2 Trade Item Orderables.

OpenLMIS can be configured with two TradeItem Orderables for Actavis and Elys.

Two product codes, one for Actavis and another for Elys, can allow staff to specifically order one or the other. They could see pack size and price differences tied to information from the manufacturers when ordering.

(see "Whether to Requisition Based on Trade Items or Commodity Types" section above)

(see same)

In addition, providing multiple choices for staff can make the ordering form longer and require more thought to fill out the form.

Requisition based on 1 CommodityType Orderable.

OpenLMIS can be configured with one CommodityType Orderable for Quinine Sulphate.

The Pack Size information in that CommodityType Orderable could be configured as 100 or 1000, or even 500 (to split the difference).

When ordering, staff will not know the exact pack sizes that would later be shipped. They can specify a quantity to order (in dispensing units) but cannot pick between packs of 100 or 1000. This may be simpler for staff and streamline the ordering process.

When ordering, staff cannot differentiate between the different pack sizes and the expected cost difference between the package sizes. One-size fits all, but few perfectly.

Requisition based on 2 CommodityType Orderables.

OpenLMIS can be configured with two CommodityType Orderables for Quinine Sulphate with pack sizes of 100 and 1,000, respectively.

This would provide two different product codes that staff could choose to order. They could choose either packs of 100 or packs of 1,000.

By using a CommodityType Orderable, there is still an opportunity for different specific TradeItems to be substituted during the fulfillment process. If a facility orders 10 packs of 100, the fulfillment staff might choose to ship 1 pack of 1000 (corresponding to Elys).

Another benefit is that each item can have different permissions on which facilities are approved to order it and could show different prices that apply for each.

Providing multiple choices for staff can make the ordering form longer and require more thought to fill out the form.

In summary, the commodity model is designed to allow orders for broad Commodity Types to be fulfilled by specific Trade Items, when the Dispensable information is compatible. As an implementation chooses how to configure OpenLMIS, they should consider all the steps in the supply chain to decide whether to use CommodityType Orderables or TradeItem Orderables.

How One TradeItems Fulfills for Another

In addition, one TradeItem may fulfill for other TradeItems when the dispensing units and dosage information is compatible. In the future this may be supported in cases where a GS1 EDI Item Data Notification message is received. For this reason, the current design (shown in the diagram below) includes a method on TradeItems called canFulfill(Orderable).

Packaging in OpenLMIS and GS1

The term "packaging" refers to the levels of containers, such as blister cells, cartons, cases and pallets, that may be used for a medical commodity. In GS1 and in OpenLMIS, each level can be a different Trade Item and can be tracked with a different GTIN. The following illustration shows an example of levels of packaging:

(Source: GS1 AIDC Healthcare Implementation Guideline release 3.0.1, July 2015, page 18, figure 3-13)

In OpenLMIS, one TradeItem can represent any one of these levels of packaging. OpenLMIS could be populated with five (5) TradeItems and GTINs for each level of packaging shown in the illustration above, from a pallet in the warehouse to one pill in the blister cell dispensed to a patient.

OpenLMIS is primarily concerned with Dispensable Units of a medical commodity. As discussed in the sections above, an Orderable item in OpenLMIS might be based on a specific TradeItem (with its unique GTIN) or might be based on a CommodityType. Regardless, any Orderable item in OpenLMIS must have Dispensing Unit information. This is important for OpenLMIS to consistently allow counting (inventory), ordering, forecasting, shipping and receiving of medical commodities.

The connections between the levels of packaging originate with the manufacturer and ideally will come directly from the GDSN network. Data from a GDSN provider may include XML data that provides additional attributes that connect one TradeItem to different levels of packaging. For example, a GTIN for a case of the product might have attributes that specify that the case contains 50 boxes.

Vaccine Vials and Doses

Similarly, this mechanism can be used in OpenLMIS to support vaccine vials. Vials usually contain multiple doses (10, 20, or otherwise). Because vials are only opened at a Service Delivery Point (a health facility that serves patients), most of the ordering, stock inventory and shipping happens with vials rather than dispensing units or doses. In OpenLMIS, the vial can be configured as the Orderable unit. The data for that Orderable will tell us about how many dispensing units the vial contains. This is now stored in the "net content" field, previously known as "pack size".

What Packaging Support is in 3.0?

In OpenLMIS 3.0, the commodity model is able to store all the TradeItems and their GTINs from multiple levels of packaging. However, OpenLMIS 3.0 does not include functionality to automatically query a GDSN provider, store the XML attributes, or use those attributes for business logic or computations.

The current model anticipates that future releases of OpenLMIS can grow in that direction. This would allow more automated calculations about orders, shipping and receiving; for example, when a case or pallet is received, its GS1 barcode could be scanned into OpenLMIS, and OpenLMIS would be able to translate that into how many dispensing units are received and added into stock/inventory.

The current model also anticipates future support for different packaging used to dispense to patients at different facilities. For example, some vaccines are distributed in multi-dose vials. Within one country's supply chain, it's possible that a smaller rural health facility is only using single-dose vials for the medication, while a larger clinic or hospital is using a multi-dose vial of that same medication. These vials would have different Trade Item records and different GTINs, but they would be connected based on the Commodity Type and Dispensing Unit information in OpenLMIS.

Kits and Re-Packaging Items

A "kit" is a set of different items that are packaged together for distribution to facilities or for dispensing together to a patient. For example, a kit could contain a single-dose injectable, an alcohol towelette, and a band-aid. This kit would be used with a patient to conduct the injection, clean the site, and apply a bandage afterwards.

Each item within the kit may be its own Trade Item and have its own GTIN. The kit and/or the items inside the kit may be ordered using the OpenLMIS requisition service or inventoried with OpenLMIS stock management.

Kits differ from the other packaging examples described above because kits contain a set of different (heterogeneous) items, whereas the example and diagram above contain multiple of the same (homogeneous) items.

In OpenLMIS 3.0, an implementation can create an Orderable record and a product code for a kit. OpenLMIS 3.0 does not currently support more advanced workflows for kits, such as: creating your own GTIN and publishing your kit via a GDSN data provider; connecting the contents inside the kit with the kit itself; tracking lots or batches once they are re-packaged inside a kit. For more about kit-related functionality that may be added in the future, see /wiki/spaces/OP/pages/57409596.

Model Diagram

The diagram below shows the domain objects and their relationships:

Historical Note

In version 2 and earlier, Products were represented but a much simpler model shown below:

The Product model in version 2 and earlier was straightforward and could be reduced to two critical pieces of information:

unique identification - both for the user as well as for connected systems
a count of the number of dispensing units in a pack

Products had many optional fields and so by way of filling in some fields and not others we could define one product within the system as something more or less specific. It could be branded or generic such as the difference between Advil and Ibuprofen. It could define the primary package's dimensions, or even the carton's dimensions and how many could fit on a pallet. Defining these, or not, influenced how one reasoned about that particular product within the system, especially within inventory and fulfillment.

See previous versions of this page and Beta to 3.0 changes for historical information.

Working Documents

Warning: The links below do not represent the final design for OpenLMIS v3.0. They contain ideas for future implementation as well as notes and working drafts: