Configuration Guide for Implementer/Administrator

This is a living document that continues to be updated as development continues. Please reach out if you have questions.

Introduction to OpenLMIS 

What is OpenLMIS?

The OpenLMIS community believes in a world where all countries have the data they need to manage their health supply chains and lead to healthier communities. We are a community initiative and a software platform working to make this vision a reality.

The OpenLMIS software is an open source electronic logistics management information system (LMIS) purpose-built to manage health commodity supply chains. OpenLMIS is rooted in the "Common Requirements for Logistics Management Information Systems" using the Collaborative Requirements Development Methodology (CRDM). OpenLMIS supports a wide range of business process needed to manage complex (multi-program and multi-level) supply chain(s). 

Additional Resources: 

• A better world through OpenLMIS Video (3:00) : 
• What is OpenLMIS? Video (20:18) : 

What business processes does OpenLMIS support?

In accordance with the "Common Requirements for Logistics Management Information Systems" using the Collaborative Requirements Development Methodology (CRDM), the following business process are supported within OpenLMIS version 3.x:

1. Requisition Business Process with the objective to ensure timely ordering of the right vaccine/drug/supply in the right quantity.
   • In OpenLMIS, the features supporting this are found within the Requisition service and enabled by the reference data configurations of products (known as orderables), min, max and targets.
2. Receiving Business Process with the objective to receive verified quantity and quality of goods into store and determine need for remedial action when necessary.
   • In OpenLMIS, the features supporting this are found within the Fulfillment service, specifically the Manage the Proof of Delivery portion.
3. Storage Business Process with the objective to maintain chain of custody and appropriate environmental conditions for stock and inventory.
   • In OpenLMIS, the features supporting this are found within the Stock Management service and supported by the CCE Management service.
4. Dispatch Business Process with the objective to identify and prepare accurate quantities of items packed correctly from store needed for transport by lower level is partially supported.
   • In OpenLMIS, the features supporting this are found within the Fulfillment service, specifically the Fulfill Orders portion. At the moment we do not support the process of planning a distribution as defined by the CRDM.
5. Transport Business Process with the objective to manage the movement of supplies between locations is partially supported.
   • In OpenLMIS, the features supporting this are found within the Fulfillment service and are limited to providing the details of the shipment and a notification when a shipment is created.
6. Dispense Business Process, both the generic and administer vaccine, with the objective to dispense effective treatment in the correct quantity and quality to the correct client with appropriate information for proper use. 
   • In OpenLMIS, the features supporting this are found within third-party applications, mainly mobile systems like OpenSRP, and are interoperable with OpenLMIS.
7. Forecasting Business Process with the objective to provide accurate estimation of goods and material needs for a specified time period.
   1. In OpenLMIS, the features supporting this are found within the Reference Data service and defined by implementers. OpenLMIS supports consumption based forecasting, minimum and maximum policies and implementer defined targets (such as target populations, etc.).
8. Capacity Planning Business Process is not yet supported.
9. Distribution Planning Business Process in not yet supported.
10. Contracts and Grants Management Business Process is not yet supported.
11. Procurement Business Process is not yet supported.

In accordance with the APICS Supply Chain Operations Reference Model (SCOR) framework, the following business processes related to Stocked Product are supported within OpenLMIS version 3.x:

What features are included in OpenLMIS? 

New features are added continuously with each release. For details on what features were added when, it is best to review the Functional Documentation page in combination with the release notes. 

Understand the replenishment process and terminology 

OpenLMIS supports "pull" (requisition-based replenishment). This is configurable on a per-program basis. For requisition-based replenishment, facilities are expected to submit requisitions for each program, on a cyclical basis, based on which schedule their "pull" program operates on. 

 The entire list of terms used in this document are located here (Glossary/Definitions) for reference as you are reviewing the Configuration Guide.

Replenishment Process and Requisition Workflow in OpenLMIS

The following is an introduction to some of the basic concepts and objects used in OpenLMIS. The words that are linked below refer to specific objects that must be created in OpenLMIS as part of setting up the system (e.g., Configuration Guide for Implementer/Administrator#Program, Configuration Guide for Implementer/Administrator#Orderables). When setting up OpenLMIS for a production deployment, a system administrator will need to create these objects in the system, in addition to several other types of objects described below that are intrinsic to OpenLMIS's operation.

OpenLMIS supports customizable Configuration Guide for Implementer/Administrator#Geographic Hierarchy for Geographic Zones or administrative areas. This includes customization of the number of Geographic Levels in the hierarchy, as well as the labels for each level in their hierarchy (for example: Country | Province | Region | District or alternatively as: Country | State | County ).

OpenLMIS supports Facilities that function as Service Delivery Points, and facilities that function as warehouses or "supply depots" to replenish other facilities. A single facility can be an SDP or warehouse, or both an SDP and a warehouse. Facilities can be further classified by type (e.g., dispensary, health center, regional hospital, teaching hospital). OpenLMIS also supports custom Facility Types which can be used to segment product availability, and for reporting purposes.

OpenLMIS supports one or more Programs, all of which are customizable. For example, a healthcare network could operate a general ART program or it could operate distinct ART programs, such as a Pediatrics ART program and a separate Adult ART program. Hypothetically, these distinct Pediatrics and Adult ART programs could be differentiated by the products available in each program.

OpenLMIS supports grouping Configuration Guide for Implementer/Administrator#Orderables or Products by category (e.g., antibiotics, analgesics, etc.). OpenLMIS uses the terms Products and Orderables interchangeably as shown in more detail in the Orderables section below. The choices for Product Categories are customizable. OpenLMIS allows segmenting products on a per-program basis (e.g., Depoprevara would be offered in a Reproductive Health program, but not in a Malaria program). Individual products can be assigned to one or more programs (e.g., Doxycycline could be used in both the Essential Medicines and Malaria programs). Products are typically further segmented by facility type (e.g., experimental ARVs could be available to teaching hospitals, whereas only fully qualified ARVs would be available at village dispensaries, since there is less concern about risks from undocumented side effects. Note that medical supplies are commonly referred to by several different terms, including orderables and products. 

OpenLMIS supports customizable Processing Schedules that define the Processing Periods or calendar intervals at which facilities are replenished. Each schedule is typically divided into uniform periods, such as months or quarters. OpenLMIS supports having multiple schedules tailored to how each program and/or geographic region is managed. For example, there could be three different quarterly schedules, each staggered to start on a different month of a calendar quarter. When performing replenishment calculations, OpenLMIS automatically takes into account the length of each replenishment interval and calculates order quantities accordingly. This is configurable on a per-program basis. For requisition-based replenishment, facilities are expected to submit requisitions for each program, on a cyclical basis, based on which schedule their "pull" program operates on. 
OpenLMIS uses a mechanism called Configuration Guide for Implementer/Administrator#Requisition Group to manage the replenishment process. A requisition group is a "container" for gathering together a group of facilities that run the same programs, on the same schedule, rely on the same supervisory hierarchy for review and approval of their requisitions, and rely on the same warehouse to fill their approved orders. The requisition group provides a convenient mechanism for managing the schedule and workflow for all these ART clinics, on a group basis.

Now that you understand the replenishment requisition and fulfillment processes, the next step will be to gather and prepare the reference data to complete the OpenLMIS setup.

Understand key roles in setting up OpenLMIS 

Step 1: Prepare

Gathering the Required Data

There are several sets of data that the team must gather, in preparation for setting up OpenLMIS. These will include (in the recommended order of loading/setting them up):

• a list of all Programs and their configuration that will be supported in your health care system
• your preferred classification scheme for facilities (FacilityTypes and FacilityOperators)
• a list of all geographic zones, plus a determination of how your geographic hierarchy will be structured (GeographicLevels and GeographicZones)
• a list of all Facilities that will be part of your health care network, including service delivery points and supply depots or warehouses; each facility includes a list of programs that are supported at that facility.
• a list of adjustment reasons available (for modifying the stock levels in requisitions and during stock management) and their assignemnts to specific programs and facility types (StockAdjustmentReasons, ValidReasons)
• a list of valid source assignments and valid destinations for shipments, proofs of delivery, and stock issuing/receiving (ValidSources and ValidDestinations)
• a list of categories to group the orderables (OrderableDisplayCategories)
• a list of all Orderables and Trade Items that will be available to health care facilities
• your classification scheme for Commodity Types
• your determination for how orderables and trade items will be segmented by program, as well as by facility type (ProgramOrderables and FacilityTypeApprovedProducts)
• your determination of the schedule(s) on which facilities will get replenished (ProcessingSchedules and ProcessingPeriods)
• your determination of how requisitions will be routed for review and approval and how many review steps will be required (SupervisoryNodes)
• your determination of how facilities will be grouped, to get replenished on the same schedule segmented by program (RequisitionGroups + RequisitionGroupProgramSchedules)
• your determination of what facilities will supply for requisitions in the given program and supervisory node (SupplyLines)
• a list of all users and their roles that will be working with OpenLMIS to support the replenishment process (Users, Roles)

Many of these sets of data may already be contained in legacy systems, stand-alone databases, or spreadsheets. The configuration steps listed below include a list of attributes or fields that must be assembled for each of the objects that you will create in OpenLMIS, e.g. facilities or orderables, and should be used to your gathering of the data. OpenLMIS has a tool that can help implementers in loading the above data: https://github.com/OpenLMIS/openlmis-refdata-seed

Initial Preparation of OpenLMIS system

Setting up an Administrator

The default administrator account that is initialized when OpenLMIS is first installed is username = Administrator password = password.

These login credentials are in the public domain and are maintained here, so the first step is to create a new user account with administrator rights, and then disable this default account. Log in with above credentials, then from the main menu, go to: Administration, Users.

Click on the [Add User] button, then enter the basic information for the new user account as well as creating a password for the account by selected the Reset Password link below.

Now the new user account needs administration rights. To set this up, go to Administration, Search for the User: Administrator, then select Edit. It will bring you to the Edit User Roles screen where you can assign the Administration type role to the user as shown below and Save User Roles. Once the user has been assigned the Administration role the OpenLMIS set up can begin.

Additional considerations before setting up OpenLMIS

OpenLMIS relies on three different methods to fully configure the system: 

• Configuring various objects in OpenLMIS, by means of various administrative user screens
• SQL statements, executed by a database administrator that insert data into the system
• Importing CSV files, as bulk uploads of various objects

Each of these methods will be used at different stages of the overall setup process to fully configure the system. Working with administrative user screens is required at various points in the setup process, starting with setting up an OpenLMIS administrator account (as shown above). Administrative user screens will also be used in the latter stages of the setup process, for example, to define the schedule(s) that your replenishment cycles will operate on, to configure requisition forms, create additional user roles, and assign new users to specific roles.

First, you will learn more about each set of data within the system. Then you will be shown how to set it up, and given an example to reference as you are completing this process. Now let's begin the process of setting up OpenLMIS.

Google translations affect the calculations. The translation plugin changes the markup causing the calculated quantities to be incorrect and breaking their update. We recommend not to use Google Translate but rather OpenLMIS built-in translations.

Step 2: Set up OpenLMIS 

In this step you will learn about setting up OpenLMIS. This step involves creating various attributes and associating reference data. The setup must be followed in this order to ensure data exists for the next attribute. This setup process includes the following:

• Setup Basic Attributes that are used to characterize Products and Facilities
• Setup Orderables, TradeItems, CommodityTypes
• Setup Programs, Processing Schedules, and Periods  
• Setup Geographic Hierarchy, Levels, and Zones 
• Setup Facilities and Facility Types
• Setup Facility Type Approved Products
• Setup Associated Facilities and Programs
• Setup Ideal Stock Amounts
• Setup Stock Management including Adjustment Reasons
• Setup Supervisory Nodes, Requisition Groups, Supply Lines 
• Setup User, Roles, and Rights 
• Setup Facility FTP 
• Setup Requisition & Report Template by program and facility type
• Setup Order File
• Setup CCE Catalog

Setup Basic Attributes that are used to characterize Products and Facilities

Product Categories

Product Categories are used to sort products by a logical order within the R&R form. These categories should make sense to any user that views R&R forms so they can associate the section they are working in as they are completing or reviewing the forms.

Setup Product Categories

Example:

• The Category Code is the shorthand name that is not visible to users. The code must be unique and is case-sensitive.  
• The Category Name is the description of the Product Category that is displayed and visible to all users. The name must make sense to the general users and have enough detail so they can identify which section of the R&R form they are viewing. When transitioning from paper requisitions to OpenLMIS, it may be helpful to categorize products the same way as they appear on the paper form. 
• The Display Order determines where on the R&R form the category and associated products are listed. 

Dosage Units

Dosage Units are the different units in which individual doses or items that are given to a patient can be quantified. 

Setup Dosage Units

Example:

• The Dosage Unit Code should correspond with the dosage units for each product. 
• The Display Order determines the order in which the available dosage units are presented to a user when creating a new product or editing an existing product.

Setup Orderables, TradeItems, CommodityTypes

Understanding Orderables, TradeItems, and CommodityTypes

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.

This Commodity Type defines the classification system:

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).

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:

*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:

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.

Setup Orderables

This is example will explain how to set up Orderables within OpenLMIS but does not complete any associations with Trade Items or Commodity Types as referenced above. The reference data for Orderables or Products within your organization will determine which setup process (Orderables, Commodity Types, Trade Items) to use when creating these objects in OpenLMIS.

Full Supply vs non-Full Supply

Full Supply orderables are Full-supply products that are assumed to have a "max periods stock" or "ideal stock amount" defined by the MoH, and OpenLMIS calculates reorder amounts to replenish SDPs up to this target amount. Non Full Supply orderables are products that are assumed to be available on an irregular basis, with no guaranteed ideal stocking level. When an Orderable is designated as Full Supply, it will appear on the standard program requisitions. Identifying when a product is Full Supply or Non Full Supply begins in the example below.

  Only include products which are needed, especially for non full supply products because it can impact performance if the list reaches into the thousands, and can decrease usability by making it challenging for users to find products.

Example of two Orderables:

• The Program identifies which programs offer the orderable. The system won't allow duplicate entries for the same program. Otherwise, it wouldn't be possible to determine which properties (like price, pack size) to use for the orderable.
• The Product Code is an identifier used to differentiate each product or orderable in the R&R form as well as other external systems the country operates. This code should be defined in your reference data.
• The Product Name is defined by the reference data gathered during OpenLMIS setup and is displayed on the R&R form for the user.
• The Description is an additional optional field that can be used to describe the product.
• The Active flag determines whether the product is available to select in the requisitioning process.
• The Full Supply flag determines if the product appears on the Full Supply tab. If the flag is FALSE, it will not appear, and if the flag is TRUE, it will appear on all requisition forms on the Full Supply tab. If the flag is set to FALSE, then no users will see this product to select in the requisitioning process within the Full Supply tab.
• The Display Order determines the line item where the product appears on the requisition form. This should match the paper requisition forms to assist in easy entry.
• If ordelable has a children it is kit.
• The Price Per Pack, Pack Rounding Threshold, Pack Size, Round to Zero, and Dispensing unit are defined by the reference data gathered for OpenLMIS setup, and may be displayed on the R&R form for the user. These fields are used in calculations within the R&R form and may affect the Total Requisition Cost.

  • The pack rounding threshold attribute affects how OpenLMIS calculates the number of packs to ship to restock a facility. Note that product inventory and usage are generally reported in "dispensing units," as part of the requisitioning process, where a dispensing unit is the basic unit that a patient is provided when the clinician or pharmacist gives them the product. However the warehouse will ship "packs" of a product, and a pack can contain one or more dispensing units. For example, a dispensing unit for an antibiotic might be a strip of 10 capsules, and the corresponding pack could be a box of 24 strips. OpenLMIS performs the initial calculations for the quantity of each product to ship an SDP in terms of dispensing units, rather than doses or packs. OpenLMIS's last step in these calculations is to round up or round down the number of packs to ship to the SDP. The value of this Rounding Threshold attribute determines when OpenLMIS rounds up or rounds down the number of packs to ship. 
    Returning to our example of strips of antibiotic capsules, if the rounding threshold is set to 6 for this product, then OpenLMIS will round up the number of packs to ship whenever the calculated order quantity of dispensing units that are beyond full packs is greater than this threshold value. For example, if the reorder quantity for the antibiotic is 52 strips, this would equate to 2 full packs plus 4 additional strips (2 x 24 + 4 = 52). Because the rounding threshold for this product is 6, OpenLMIS will round down the order to 2 packs. Conversely, if the reorder quantity for the antibiotic is 55 strips, this would equate to 2 full packs plus 7 additional strips (2x24 + 7 = 55). Because the rounding threshold for this product is 6, and the 7 additional strips exceeds this threshold, OpenLMIS will round up the order to 3 packs. Remember, packs are the units in which the warehouse ships products. Note also, OpenLMIS rounds up when the extra number of dispensing units is greater than the threshold, not when it is greater than or equal to the threshold.
    The can round to zero attribute determines whether OpenLMIS will round the number of packs to ship down to zero when the reorder quantity is less than one full pack and is less than or equal to the rounding threshold for this product. For our antibiotic example, if the reorder quantity was 6 strips (equal to the rounding threshold), then OpenLMIS would round the order quantity down to zero packs if can round to zeroes true. Conversely, it would round the order quantity up to one if can round to zeroes false. In other words, when can round to zeroes set to false, OpenLMIS will always ship at least one full pack when the reorder quantity is one or more dispensing units. If the reorder quantity is zero dispensing units, then OpenLMIS will ship zero packs, regardless of the value of can round to zero.

    Program (required)	Product Code (required)	Product Name (required)	Description (optional)	Active (required)	Full Supply (required)	Display Order (required)	Price Per Pack (optional)	packRoundingThreshold (required)	netContent (required)	roundToZero (required)	dispensingUnit (optional)	children (optional)
    Essential Meds	AA000300	Mercaptopurine		TRUE	FALSE	1	2154.65	1	1	FALSE	Each
    Family Planning	FP000400	Postinor (Levonogesterol)		TRUE	TRUE	1681	6940.30	1	1	FALSE	Each

Now that you've used your reference data to complete the setup of Orderables, the next step is to set up the objects for Programs, Processing Schedules, and Periods.

Setup Programs, Processing Schedules, and Periods 

Understanding Programs, Processing Schedules, and Periods

A Program is a grouping of Orderables and Trade Items. Each Program has:

• A specific set of Orderables
• A complex configuration including Requisition Form settings and Program-specific user permissions
• 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 though 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. 

A Processing Schedule must be defined for each Program so that you can determine the Requisition Groups that are required. Processing Schedules are required to determine the Requisition Group that is used to operate the Program at that facility. For requisition-based replenishment, facilities are expected to submit requisitions for each program, on a cyclical basis, based on which schedule their "pull" program operates on. There can be many different processing schedules for varying Programs in the same Requisition Group, but they cannot be different processing schedules for the same Program in the same Requisition Group. This scenario creates confusion on which schedule the program's requisition workflow follows.

Once a schedule has been created, you need to define the individual periods that comprise the schedule. Processing Periods define individual start and end dates associated with a Processing Schedule. OpenLMIS allows you to specify any "start date" and "end date" for each period in a schedule and makes no assumptions about automatically creating periods for a new schedule. New periods are not automatically created so the administrator must create them as needed, to not delay the creation of requisitions. The start date can be further back in time to support migration of data from a legacy system, however there can be no gaps between two consecutive periods. As you are creating periods, the system automatically sets the start date for the new period as one day after the end date of the preceding period. The system does not allow deleting periods once replenishment activity has been initiated for that period, and also does not allow deleting a period from the middle of a schedule.