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.

Setting up Programs

• Program Codes are the short hand description of the Program and are only visible to the administrator, but can be reused when naming the Supervisory Nodes. 
• The Name is the detailed description of the Program and is visible to all users. The name should provide enough detail that the user knows the difference between multiple programs if they have access to more than one program that have small variations. For example there may be more than one HIV program because they operate on different budgets. If this is the case you must make sure that the name provides enough information for the administrator to choose the correct program during assignment. 
• The Description is not required but is used to provide more detail to the name. The Description is not visible to users other than the administrator.
• The Active flag determines whether the Program is available to use in the requisition process. If a Program is set to Active = TRUE, then this means users can see this program to start requisitioning. If the Active flag is set to FALSE, then the Program is not available for the requisition process. This is helpful if a new program needs to be set up early. Once the program is ready to use the administrator would change the designation to TRUE.
• The Allow Skipping Periods designation identifies if a requisition for the next period can be skipped. This is typically enabled when OpenLMIS is first set up and processing schedules have been created for prior periods. A requisition must be created for the next available period, unless the administrator has allowed to skip periods. For example if the next available requisition period in OpenLMIS is July 2017, but the current calendar date is October 2017, then the user would need to enter in requisitions for July, August, and September before they could start October. If the administrator has allowed to skip periods, then the user could skip July through September and start on October. If this designation is set to TRUE, then the administrator has enabled skipping periods. This is also useful if users have not completed requisitions for previous periods, but need to enter a requisition for the current period. If this is set to FALSE then the requisition must be completed for every period in the order of the defined schedule. This feature addresses issues with data capture on a routine basis when a facility hasn't been reporting for awhile. In this case, there are empty requisitions for the missed reporting periods, but they need to complete a requisition for the current period. This does cause issues with reporting for the skipped periods so it should not be used often. 
• The Show Non Full Supply tab designation determines whether a program shows the Non Full Supply tab within a requisition. An orderable is considered Non Full Supply because they are available on an irregular basis. If the designation is TRUE means that the Non Full Supply tab will appear for the Program. If the designation is set to FALSE, then there will not be a Non Full Supply tab when viewing the requisition for that program. 
• The Skip Authorization Step flag determines whether the authorization step is enabled in the requisition workflow for this program. When this flag is set to true, the authorization step will not take place and the submit operation will bring requisitions of this program directly to the AUTHORIZED state (ready for approval). The changes to this setting are applied immediately to all requisitions. This means that the additional step of Convert to Order is no longer required and a requisition will automatically update to the Released without order status. This must be configured as TRUE when a facility and program are fulfilled locally.

 If the requisition has already been submitted though, and had its authorization step skipped, it will still be available for approval, even after disabling this flag.

Example:

 Any changes to Program Settings are effective immediately

Setting up Requisition Date Physical Stock Count Completed

An optional setting allows you to configure whether the Requisition Form for each program will prompt users to enter a 'Date Physical Stock Count Completed' or not. 

Administrators can enable or disable this under Administration > Programs > Program Settings (screenshot above). By default, this is disabled for each Program. If you Enable it and click Save, it will take effect for all Requisitions for that Program. 

When this setting is enabled for a program, any user Submitting or Authorizing a Requisition in that program will be prompted to enter a date that the Physical Stock Count was completed:

The date prompt first appears when a user Submits a Requisition. A date is required at that time. The date prompt appears again when a user Authorizes the requisition, allowing the authorizing user to view and change that date, if desired. For requisitions where this date has been entered, the date appears in the gray header at the top of the Requisition for all users who can view the Requisition.

The Requisition form saves some of its data in the Stock Management service so that it can be viewed on stock cards. When the setting is enabled, the date captured during the Requisition submission and authorization will be used by the Stock Management service to record the stock quantities as of that specific date. When the setting is disabled, then no such date is captured from users, and the Stock Management service will record stock quantities by using the ending date of the requisition period.

The benefit of enabling this setting is more accurate stock transaction records, although it does require users to conduct data entry of a date during the requisition process.

This setting takes effect immediately, including for in-progress Requisitions. Administrative permissions (to the Program Settings page) are required to change this setting. As soon as this setting is enabled or disabled, users Submitting or Authorizing a requisition will notice this change. This feature was first introduced with OpenLMIS 3.2.0. For background about this feature, see the ticket OLMIS-3023 - Getting issue details... STATUS  as well as the wiki documentation Connecting Stock Management and Requisition Services.

Setting up Processing Schedules

• The Processing Schedule Code is a shorthand description for the Processing Schedule that is only used during initial set up. 
• Processing Schedule Name should clearly identify how the schedule will be set by an administrator. This example shows Monthly schedule, but there could also be a Quarterly Schedule. When the administrator creates processing periods they will select the Processing Schedule by this name and create the periods to match. The Monthly Schedule would have a period for each month. 
• The Processing Schedule Description is an optional field that could provide more detailed information on the processing schedule.

Example:

Setting up Processing Periods

• Processing Periods must be defined by the administrator to ensure that requisitions can be entered. Processing Periods are not automatically set up and the administrator must create periods for all the future requisition processing periods so that requisitions are not delayed.
• The Name is a short hand description of the Processing Period and is visible to the users when completing the requisition workflow. The name should provide enough information for a user to understand the period they are completing for their requisitions. This example shows a processing period for each month. If the Processing Schedule was Quarterly, the Processing Period names could be Q1-2017, Q2-2017, Q3-2017, Q4-2017, Q1-2018, etc. 
• The Description is a more detailed explanation of the Processing Period. The example shows the Monthly Processing Period, but if the Processing Period was Quarterly the description could be: Processing Period for First Quarter of 2017, then Second Quarter of 2017, and so on.
• The Start Date is the date when the period will start, and the first start date should match when your organization will begin requisitioning. In this example the start date is the first day of the month, but does not have to start on the first day of the first month. If your organization begins using OpenLMIS in the middle of the year, the first start date could be July 1, 2017. If the Processing Period was Quarterly, the start date could be January 1, 2017 for the first period, and then April 1, 2017 for the second period. 
• The End Date is the date when the period will end, and must be at least one day after the Start Date. In this example the end date is the last day of the month. If the Processing Period was Quarterly, the end date could be March 31, 2017 for the first period, and then June 30, 2017 for the second period.
• Once the first period is created, the system pre-populates the next period's start date as one day after the previous period created for this schedule.
• The Processing Schedule is the Processing Schedule code created above. To complete the creation of the Processing Schedules you must assign the Processing Period their related Processing Schedule. In this example the Processing Schedule is Monthly (MPS). If the Processing Periods were quarterly, the Processing Schedule could be Quarterly (QTR). 
• The Report Only flag allows the administrator to configure requisition processing periods to no longer require a user to enter a requested quantity into a requisition. The report only flag default is false (unchecked). When the flag is set to True (checked) then this period is considered a report only period and this requisition will not result in a requisition being converted to an order. This flag only applies to regular requisitions.

Example: 

Now that you have completed set up of the Programs and associated schedules, you will setup your geographic hierarchy.

Interfacing with a facility registry for locations

(In here we will also need to explain the process of how locations are created, the resources used and unused, how the update process works, and the association between facility and geographic zone: Chongsun Ahn (Unlicensed) to update)

There are two primary use cases that can benefit from an FHIR server implementation in terms of OpenLMIS serving mCSD locations as a provider and consuming locations as an update consumer.

Use case 1: OpenLMIS serving mCSD Locations (Care Service Update Provider)

In this use case, the assumption is that the OpenLMIS implementation is a Care Service Update Provider. OpenLMIS owns an authoritative list of some or all of the Locations and provides those to the federated master facility list management infrastructure. Parts of the facilities that OpenLMIS owns includes supply chain locations like stores, dispensary units.  To support such an implementation with as standard compliant service as possible, OpenLMIS can expose read-only FHIR Location resources. In the OpenHIE Architecture, a mediator is able to access the FHIR Location resources that are exposed from OpenLMIS and populate the Interlinked registry. 

OpenLMIS v3.5 uses a FHIR server running as a microservice in OpenLMIS. 

Use case 2: OpenLMIS as a consumer of mCSD Locations (Care Service Update Consumer)

Assumes that there is an implementation of an Authoritative Master Facility List that supplies mCSD conforming Location resource. In this case, OpenLMIS needs to be able to consume those Locations and Updates as mCSD update consumer. The Locations from the other owners are created in the OpenLMIS as appropriate entities like geographic zones and facilities. However, In OpenLMIS, no update is allowed to be made on these Locations that are created and owned by others. 

Setup Geographic Hierarchy, Levels, and Zones 

Understanding Geographic Hierarchy, Levels, and Zones

OpenLMIS identifies facility locations using a Geographic Hierarchy that is made up of Geographic Levels and Zones. A Geographic Hierarchy helps in outlining the characteristics that make up each level and zone. Geographic Hierarchy also supports reporting, especially when doing comparison reporting of certain trends by region or district. An example of a Geographic Hierarchy is Country, Region, District, where the first level in the Hierarchy is the Country, the second level is Region, and the last is District. A Geographic Level is each level within the hierarchy. A Geographic Zone is the lowest level of the hierarchy and facilities are assigned to a Geographic Zone in the Facility setup detailed in the next section. Although a Geographic Zone is the lowest level of the hierarchy, it does not need to be a the lowest possible level a facility is identified. For example, you would not set up a separate Geographic Zone for every facility, but instead determine the lowest level that reporting needs to use, unless the system is only supporting one facility. Then the setup would only have one zone and one level.

Setting up Geographic Levels and Zones

When defining Geographic Levels you should consider the level that your organization operates on, and which level has the highest rank. If you are operating only regionally, then the Region or Province would be at your highest level, but if you are operating Nationally, then the Country would be your highest level. When creating the hierarchy and levels there is a natural parent to child hierarchy that needs to be defined in the system. The Geographic Zone should be the lowest level that your organization needs to use for reporting because it defines the location of a facility, and the zone is used when creating facilities to associate in reporting. A system intended for use at the national level should use something analogous to “Country” as the highest-defined Level. Likewise, an instance of OpenLMIS intended for use no higher than at a regional Level should something like “Region” as the highest-defined Level. In all cases, the lowest-defined Level should correspond to the most specific  granularity within which facilities should be defined.

Geographic Level Example:

• The Geographic Level explains the facility hierarchy and in this example is defined by country, zone, district. For Geographic Levels in this example the Country is the highest level, Malawi. The Zone is Northern, Southern, and Central, and the Districts are Lilongwe, Ntcheu, and Balaka as examples, which happen to be cities in Malawi. Other examples of Geographic Levels is Country, Province, Region or Country, State, County.
• When setting up Geographic Level, the Code should describe the different levels that exist within your hierarchy. This example shows Country, Zone, District, but the code can also be a shorthand description:
  • Country: CTRY
  • Zone: ZN
  • District: DST
• The Name should describe the Code in more detail, in this example they are the same. 
• The Level Number determines the order of each level in the hierarchy and must be a number. In this example Level 1 is at the top of the hierachy, which is the Country level, and the next level is 2 - Zone, then 3 - District.

Geographic Zone Example:

• The Code for Geographic Zones is a short hand identification for each zone. This is only visible during the initial set up but is also used in this setup to identify the parent to child relationships.
• The Name for Geographic Zones is a more detailed description of each zone. This is visible to administrators as they are setting up facilities, and visible to users in reports. 
• The Level explains the Geographic Level that each entry is associated with and corresponds with the Geographic Level Code that was created in the above section. The Geographic Level tells OpenLMIS where the zone fits in the overall Geographic Hierarchy.
• The Parent must be associated with any levels below the top Geographic Level. Associating the parent to child relationship ensures that the reporting structure is correct. The Parent is not required for the top level, but is required for all other levels.
• The Catchment Population is the nominal population for the Geographic Zone and is used to calculate coverage rates, or compare consumption relative to population. This attribute is optional, and commas should not be included in these numbers.
• The Latitude attribute is the latitude for the zone. A single latitude value cannot fully characterize a country. Instead, this latitude value is typically based on the centroid of the country, and would most commonly be used for positioning markers on a geoplot diagram. 
• The Longitude attribute is the longitude for the zone. As with the latitude, this longitude value is typically based on the centroid of the country, and would most commonly be used for positioning markers on a GIS map.
• All latitude and longitude values are expressed as decimal numbers in 8,5 format. This means each value can have a total of up to 8 digits, with up to 5 digits after the decimal point. Positive values for latitude indicate a northern latitude; negative latitude values indicate a southern latitude. Positive values for longitude indicate an eastern longitude; negative longitude values indicate a western longitude. Note that the numbers after the decimal point represent fractional degrees, rather than arc minutes or seconds.

Now that you have completed the Geographic Levels and Zones, you will use the objects to set up your Facilities.

Setup Facilities and Facility Types

Understanding Facilities, Facility Types, and Facility Operator

Facility Types and Facility Operator

Facilities in OpenLMIS is a term used to identify a location that is part of your requisition process. These can be identified by facility types such as health clinics, district hospitals, or warehouses, or even as multiple locations within a district hospital or health clinic. Facilities are used in all of the modules of OpenLMIS: the requisition process, fulfillment, stock management, orders and reporting. Facilities may have one to many Programs and one to many Processing Schedules. A facility cannot have the same Program on different Processing Schedules. Facilities must be set up in order to begin user setup and management for requisition and fulfillment based roles.

Facility Types are used to allow the different assignments of facility type approved products. Reports from the system also list the facility type for reference. There can be many different facility types such as health clinics or district hospitals. Facility Types are also used to assign a program with multiple templates.

The Facility Operator is not required but is useful when generating reports (such as a coverage rate comparison by facility operators). The Facility Operator can be defined in terms of the types of organizations that are operating at facilities. Examples are Ministry of Health or Doctors with Borders. 

Setup Facility Type, Facility Operator, and Facility

First the Facility Type and Facility Operator must be set up because these sets of data are used to support the setup of a Facility. For each Facility Type a type, name, description, display order, and active designation should be defined, but not all fields are required. The Facility Operator is not required.

Facility Type Example:

• The Facility Type must be defined before you set up facilities. A facility type can be used to segment product availability, and allows for flexibility in the configuration of requisition templates used in the requisitioning process. Product availability is defined in the next section for Facility Type Approved Products.
• The Facility name is required because it is visible to users as they complete their requisitions and other functions. The name is used to easily identify the facility and should be familiar to the users.
• The Facility description is optional and only visible to the administrator but assists in providing more detail.
• The Display Order is required and determines the order of the facilities within a dropdown in the user's view.
• The Active designation is required and determines whether a user can see the facility. If a facility is inactive (Active = No) then the facility will not appear for any user. Facilities are not deleted from the system, but only marked as inactive and disabled.
  

Facility Operator Example:

• The facility operator code attribute is shorthand for the facility operator name and is never seen by general users.
• The name attribute is used as the actual display name in OpenLMIS for each facility's operator, and thus visible to general users.
• Display order determines the order in which the available facility operators are presented to a user when creating a new facility or editing an existing facility.

  If a facility is no longer in use, updating the Active designation to 'No' will not remove the facility from all user's views. An inactive facility remains in a user's navigation menu for historical purposes, such as viewing historical reports.

Facility Example:

• The Facility Code is an identifier that must be unique per facility that is visible to the administrator and to users in their reporting. 
• The Name is the common name for the facility. The facility name appears on most screens and is used to assist in navigation or forms.
• The Description is optional and can be used to provide more detail to the administrator about the facility.
• The Geographic Zone is a required selection based on the geographic zones set up in the Geographic Zone section above.
• The Facility Type Code is a required selection based on the facility types set up above.
• The Active designation determines whether or not whether or not it can submit requisitions or receive deliveries. This should be set to Active (True = Yes, or False=No). A facility can be set to inactive if it is temporarily shut down but resumes activity at a future date.
• The Go Live Date (Operational Date) is required and is used in reporting to record the date the facility becomes operational.
• The Go Down date is optional.
• The Comment field is optional.
• The Enabled field is a required designation that determines whether the facility can operate (True = YES), or has been permanently decommissioned (False= NO).
  
  

Associate Facilities and Programs Supported

Understanding Associated Facilities and Programs Supported 

Once facilities are set up you must assign the programs and details associated with each facility. Facilities in OpenLMIS can support one to many programs that are available at one to many facilities (with some variations). Assigning a program to a facility qualifies the program and its related orderables to be used in the requisitioning process for that facility. A facility must be assigned a program that is active, as well as a valid start date for that program in order to be used. Designating a program to be fulfilled locally is also a part of the set up of facilities and associated programs.

Associate Facilities and Programs

Example:

• The Facility Code is the identifier assigned to each facility during the setup process described above in the Facility set up.
• The Program Code identifies the program that will be supported at the facility and must be one of the programs defined in the Program set up process above.
  • In the Administration menu under Facilities, after selecting a facility, once a program is assigned to the facility, the associations are made with the Facility Code and Program Code. 
• The Active designation indicates whether the program is active at the facility. The default should be NO (False), but if the program is active then a start date must also be entered.
• The Start Date is required only if the Program is Active flag is set to True (Yes). The start date determines the first date available that the user will enter in requisitions related to the program. For example, if the start date is set to two months prior, then the user must begin requisitioning two month's prior. If the start date is set two months in the future, the user will not be able to enter in requisitions until that date.
• The Locally Fulfilled field allows for configuration of whether a facility's supported programs can be fulfilled locally, instead of through external fulfillment. By selecting the Locally Fulfilled checkbox, the program will also skip the Convert to Order step in the fulfillment process.

Example of facility that is fulfilled externally:

Example of facility that is fulfilled locally:

Facilities and FHIR Locations

OpenLMIS comes with a built-in facility registry that is compatible with a subset of the Mobile Care Services Delivery (mCSD) profile of the Fast Healthcare Interoperability Resources (FHIR) specification. This is for interoperability with other facility registries in order to easily synchronize data as it is managed.

To support the mCSD profile, OpenLMIS exposes facilities and their geographic data as FHIR Locations. The system also handles facility updates by automatically syncing changes to the corresponding locations. As long as the built-in FHIR server is running, no additional configuration is necessary.

Setup Facility Type Approved Products 

The purpose of Facility Type Approved Products allows you to segment orderables by facility type. Although a program supports a specific list of orderables, different facilities may not have the capacity to support providing the orderables. This is why you would want to segment orderables by facility type. Each facility that performs duties related to the requisition process must be set up with their Facility Type Approved Products.

Setting up Facility Type Approved Products per Orderable

• The Facility Type is the Facility Type code identified in the Facility setup process. This determines which facility types will have the orderables available in their requisitions. 
• The Orderable is the orderable name from the orderables setup process. An orderable can be approved for many facilities and programs or an orderable may only be available at certain facility types like District Hospitals instead of Health Clinics because there is limited space. 
• The Program is the Program Code that is associated with the orderable in the orderables setup process. In this example you can see the orderable is available for two different programs: Essential Meds and TB, and at two different Facility Types: heac (health center) and DHO (District Hospital). 
  
• MaxPeriodsofStock is the maximum number of periods used for the MaxPeriodsofStock calculation in the requisition template. 
• MinPeriodsofStock is the minimum number of periods used for the MinPeriodsofStock calculation in the requisition template.
• EmergencyOrderPoint is not required. The Emergency Order Point attribute is intended to specify the emergency order point for a facility. This attribute is not used by OpenLMIS for replenishment calculations. It is included as a convenience and listed in the header of each requisition as a general guideline.

 It is important to correctly configure the Max Periods of Stock per Product because it is included in the calculation for the Dispensing Units and affects the Total Cost on every requisition. (This is detailed more in the R&R Template section below.)

Now that you have set up your facilities you are ready to set up the objects that enable the workflows in OpenLMIS.

Setup Ideal Stock Amounts

Understanding Ideal Stock Amounts

The Ideal Stock Amount is a yearly estimate of the “target” number of doses of a vaccine you should have based off of your population served (i.e. catchment population). This model for estimating the number of vaccine doses you need is irrespective of vial size, packaging, manufacturer, etc. so that you focus on a single number of doses that you should have at any given time. For more rural service delivery points, this time is typically the number of doses you should have in a year, divided by 12 months with the idea that your refrigerator can only hold up to about a month's worth of vaccines at a time. The Ideal Stock Amount (ISA) can be used in reordering calculations for OpenLMIS for a vaccine program.

Setting up ISA by Facility, Commodity Type and Period

Ideal Stock Amounts (ISAs) are configured by facility code, commodity type, and period. An initial load of ISAs is done by uploading a .csv file with the following columns:

• Facility Code is the Facility that will be associated with the ISA.
• Commodity Type can be the UNSPSC code from https://www.unspsc.org/ 
• Period is the period or schedule that the ISA will be applied to, for example an ISA for the year may be 200,000 while broken down by a monthly reporting period would only equal to 
• ISA

 Any updates to the ISA can be done by exporting the ISAs into a csv file and completing the steps listed on Administration > Ideal Stock Amounts > Manage Ideal Stock Amounts page.

Setup Stock Management 

Stock Management is the process of managing stock by recording physical inventory utilizing stock cards, and using reason categories to record and track stock movements. In the Stock Management screens as well as in the Requisition form, storeroom managers need to record the reason for each stock event, e.g. adjustment, receive or issue. First, you must configure adjustment reasons for each stock event.

Setup Adjustment Reasons

OpenLMIS provides a page for the system administrator to manage the reason list. There are reason categories ('Transfer', 'Adjustment', and 'Aggregation') and reason types ('Debit' and 'Credit'). 

• An Adjustment or Transfer category is a predefined type of stock movement that is configured with reasons for a user to select and associate with the stock movement. 
• The Receive and Issue stock movement types record two standard movements that adjust stock levels. The Receive type occurs when a facility has received stock that wasn't requested through the regular requisition workflow. The Issue type occurs when a facility needs to issue stock that wasn't requested through the regular requisition workflow. 
• Credit or Debit is used to assist in the calculations for Stock on Hand. When creating different adjustment types, you must select whether the adjustment is a credit (addition or positive) to the stock on hand or a debit (subtraction or negative) to the stock on hand. 

•  A reason can allow free text. By allowing a reason to support free text, a store manager can input a description to this reason to provide more detail about the reason. For an example, a reason labeled 'Other' is a 'transfer' category and 'credit' type reason. When the storeroom manager chooses this reason for a receive stock event then the storeroom manager can input description (e.g. NGO-VR) to explain the reason 'Other'.

• Aggregation
• The reason type 'Unpacked from kit' and 'Unpack kit' are only specific to kits (products that have children).

When creating a new Reason the following fields are required or optional:

• The Name field is required and is a free text field that is a short explanation to the user about the Reason.
• The Category field is required and determines whether the Reason is an Adjustment or a Transfer. An Adjustment is used for an adjustment type stock event, while Transfer is used for receive/issue stock events.
• The Type field is required and is used in the requisition or stock management calculation and determines whether the reason is a credit (positive or an addition to stock) or debit (negative or subtraction from stock). 
• The Allow Free Text field is optional and is enabled (checked) when a reason may need more details added to it that the end user enters as they are adding adjustments or transfers. 
• Tags are an optional way to group reasons. They are a free text label assigned by the implementer or administrator. For example there are individual reasons such as "Facility return" and "Receipts" that are tagged with "received". This means the individual reasons can now be grouped in a report by using that one tag "received". 
• A Program is required to be assigned to a new Reaso