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

This is a step by step guide for the Implementer that explains what's needed to set up OpenLMIS and a step by step guide to complete the setup of OpenLMIS version 3 (In Progress - document updates for version 3.5 in parentheses below)

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: 

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.
  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.
  3. Storage Business Process with the objective to maintain chain of custody and appropriate environmental conditions for stock and inventory.
  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.
  5. Transport Business Process with the objective to manage the movement of supplies between locations is partially supported.
  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. 
  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. 


(lightbulb) 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#ProgramConfiguration 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):

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: 

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

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:

Category Code (required)

Category Name (required)Display Order (required)
FPFamily Planning10
hivHIV Control Program Medicines14


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:

Dosage Unit Code (required)Display Order (required)
mg1
ml2






Setup Orderables, TradeItems, CommodityTypes

Understanding Orderables, TradeItems, and CommodityTypes




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.


(lightbulb)  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:


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:

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

(info) 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:

Program Code (required)Name (required)Description (optional)Active (required)Period Skippable (required)Show Non Full Supply tab (required)Skip Authorization Step (required)
PRG002Essential MedsEssential Medicines ProgramTRUETRUETRUEFALSE
PRG001Family PlanningFamily PlanningTRUETRUEFALSEFALSE
PRG004EPIEPITRUETRUETRUETRUE


(warning) 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  as well as the wiki documentation Connecting Stock Management and Requisition Services.


Setting up Processing Schedules

Example:

Setting up Processing Periods

Example: 

Name (required)Description (required)Start Date (required)End Date (required)Processing Schedule (required)Report Only (requisition setting)
Jan-18Processing period for January 20181/1/181/31/18MPSFALSE
Feb-18Processing period for February 20182/1/182/28/18MPSTRUE
Mar-18Processing period for March 20183/1/183/31/18MPSTRUE


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

Code (required)Name (required)Level Number (required)
CountryCountry1
ZoneZone2
DistrictDistrict3


Geographic Zone Example:


Code (required)Name (required)Level (required)Parent (optional)Catchment Population (optional)Latitude (optional)Longitude (optional)
MalawMalawiCountry



cwesCentral WestZoneMalaw


cestCentral EastZoneMalaw


seasSouth EastZoneMalaw


NUNtcheuDistrictcwes


LLLilongweDistrictcwes


BLKBalakaDistrictseas



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:


Facility Type (required)Name (required)Description (optional)Display Order (required)Active (required)
WarehouseBalaka District WarehouseBalaka District Warehouse3Yes
Health CenterKankao Health FacilityKankao Health Facility1Yes
District HospitalBalaka District HospitalBalaka District Hospital2Yes


Facility Operator Example:

CodeNameDescriptionDisplay Order
MOHMinistry of HealthMinistry of Health1


(lightbulb)  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:

Facility Code (required)Name (required)Description (optional)Geographic Zone (required)Facility Type Code (required)Facility Operator (optional)Active (required)Go Live Date (Operational Date - required)Go Down Date (optional)Comment (optional)Enabled (required)
HF01Kankao Health Facility
Southern RegionHealth Center

YES

01/01/2016

YES
WH01Ntcheu District Warehouse
Ntcheu DistrictWarehouse
YES01/01/2016

YES


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:

Facility Code (required)Program Code (required)Program is Active (required)Start Date (optional)

Locally Fulfilled (optional)

HC01Family PlanningYES
FALSE
HC01Essential MedsYES
FALSE
N003EPIYES
TRUE

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


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

facilityType (required)orderable (required)program (required)maxPeriodsOfStock (required)minPeriodsOfStock (optional)emergencyOrderPoint (optional)
heacTB000100em331.5
heacTB000100tb331.5
DHOTB000100em331.5
DHOTB000100tb331.5


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 (required)Commodity Type (required)Period (required)ISA (optional)
N030UNSPSC|51201621SCH001|Mar20188900
N080UNSPSC|51201647SCH001|Dec20171000


(lightbulb) 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'). 



Category

Reason Type: Credit

Reason Type: Debit

TransferReceiveIssue
AdjustmentPositive adjustmentNegative adjustment
AggregationUnpacked from kitUnpack kit


Starting with version 3.2.1, you can select whether reason for Program and Facility Type should be shown or hidden. The default for new reasons is 'Show', but if you un-check the Show setting, then that reason will not be displayed in the Requisition form Total Losses and Adjustments and also will not appear in the Stock Management adjustments form.

Introduced in version 3.2.0, the requisition columns for Beginning Balance, Received Quantity, and Consumed Quantity now get mapped to stock management reasons. Those reasons are first configured as Valid Reason Assignments in the stock service and are visible in the Total Losses and Adjustments modal. The specific 4 reasons which are configured in the .ENV file are: CONSUMED, RECEIPTS, BEGINNING_BALANCE_EXCESS and BEGINNING_BALANCE_INSUFFICIENCY.

For Requisitions to be approved, there must be 4 reasons configured in the Requisition service, and those 4 reasons must be valid reasons for all Program and Facility Types using Requisitions. These 4 reasons should be set to hidden (un-check Show), and the Requisition service will still be able to use them even though they are not shown on the list when end-users select reasons.

See an Example request in Postman for Facility Type Health Center, Program Family Planning from demo data and CONSUMED Reason:


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

Example:

Name (required)Category (required)Type (required)Allow Free Text (optional)Tags (optional)Program (required)Facility Type (required)Show (required)
ReceiptsAdjustmentCreditFALSE

received

adjustment

  • Family Planning
  • Essential Meds
  • EPI
  • Health Center
  • District Hospital
  • District Store

DamageAdjustmentDebitFALSE

adjustment

debit

  • Family Planning
  • Essential Meds
  • Health Center
  • District Hospital
  • Warehouse
TRUE
Cold Chain FailureAdjustmentDebitFALSE
  • EPI
  • Health Center
  • District Hospital
  • Warehouse
TRUE

(lightbulb) You can select multiple programs and facility types for each reason to be valid/enabled at. Sharing Reasons across programs is recommended for consistency of reporting. We do not recommend making repeated/duplicate copies of the same reason for the use by different programs unless there is a difference in meaning or use for the different programs.


Process

  1. Go to the Administration > Reasons page via the navigation bar:

2. Click 'Add Reasons':

3. Fill in required fields to create a new reason, including adding all Programs, corresponding Facility Types for which the reason should be valid/enabled and set whether this assignment should be shown or hidden:


5. Stock Reason Tags are used to group reasons. For Stock-Based requisitions, configuring the stock reason tags will enable the system to group stock events to calculate the required stock card columns. This is defined more in the Requisition Template section of the Configuration Guide.

6. After you click Add New Reasons, the Reason is added and the updated list is displayed:

Once added, the new reasons will immediately be available in the Stock Management screens based on Program and Facility Type. The reasons will be applied to new Requisitions when they are initiated. Requisitions use these reasons for the "Total Losses and Adjustments" field that is collected for each product on the requisition form.

(warning) Requisitions initiated prior to the addition of new reasons, will use the reason list that was in place at the time they were initiated.  


In version 3.6 we introduced support for kits in Stock Management. A kit is delivered and received into inventory as any other product would be. After the delivery the recipient's stock is incremented as a kit (not for the constituent parts). After the kit is received into inventory, optionally the kit might be unpacked. If unpacked then the constituent parts of the kit are added into inventory, and the kit is decremented from inventory. When a kit is unpacked, it is considered as consumed, and is not associated with the consumption of its constituent parts. 


Setup new organizations for Stock Management events

Understanding new organizations

The Stock management service allows the system administrator to create new organizations in the system to be the source/destination for the receive/issue stock event. As of OpenLMIS 3.2.0, Organizations are only used in the Stock Management screens, but not used within the Requisition form. Adjustments recorded in the Requisition form do not have source/destination information.

New created organizations are free-text allowed default setting. Meaning, all the added organizations support free-text but this free-text description field is optional and user can leave it blank. 

Process:

Go to the swagger API - https://test.openlmis.org/stockmanagement/docs/#!/default/post_api_organizations

Find the below API and send a post request in order to create new organizations. 

There is another API to get the full set of all created organizations:

Assign/Cancel organizations/facilities as Destination in Stock Management

The Stock management service allows the system administrator to assign facilities or organizations as the destination of an issue stock event for a specific program and facility type combination.

Process:

Go to the swagger API - https://test.openlmis.org/stockmanagement/docs/#!/default/post_api_validDestinations

Find the below API and send a post request in order to assign organizations/facilities to a facility type and program.  

Among those fields in the request body, there are three mandatory fields:

facilityTypeId - determines which facility type is assigned to 

referenceId - is the ID of a facility or an organization. 

programId - determines which program is assigned to 

Moreover, we also provides the API to remove the assignment. 

Go to the swagger API - https://test.openlmis.org/stockmanagement/docs/#!/default/delete_api_validDestinations_id

Find the below API and send a request to call this API in order to remove the assignment of organizations/facilities for a facility type and program. 

Configure Valid Destinations/Valid Sources through csv files

In order to present the example configuration for valid destinations and valid sources, the exemplar facility types and facility codes are presented below:

facilityTypefacilityTypeCodefacilityCode
ClinicprivCFAC01
Private HospitalprivHFAC02
WarehousewarehouseFAC03
ClinicprivCFAC04
Private HospitalprivHFAC05
WarehousewarehouseFAC06

In this example there are three facility types (Clinic, Private Hospital and Warehouse) and six facilities of each type.

Valid Destinations table, apart from program code, consists of facilityTypeCode and destination columns.

In facilityTypeCode column there should be all codes of facility types which are able to supply other facilities. In destination column there should be facility codes of facilities which are supplied by a facility of type indicated in facilityTypeCode column.

The Valid Destinations table for these configuration is created below:

facilityTypeCodedestination
warehouseFAC01
warehouseFAC02
warehouseFAC04
warehouseFAC05
privCFAC01
privCFAC04
privHFAC02
privHFAC05

Valid Sources table, apart from program code, consists of facilityTypeCode and facilityCode/organizationName.

In facilityTypeCode column there should be all codes of facility types which are to be supplied by warehouses or organizations.

In facilityCode column there should be codes of facilities which supply other facilities. Most often it will be a warehouse.

In organizationName column there should be a name of a supplying organization if there is such.

The Valid Sources table for these configuration is created below:

facilityTypeCodefacilityCodeorganizationName
privCFAC03
privHFAC03
privCFAC06
privHFAC06

In the table there are warehouses’ facility codes (FAC03, FAC06) in the facilityCode column. It means that these facilities supply facilities of privC and privH facility types.



Setup Supervisory Nodes, Requisition Groups, Supply Lines 

Understanding Supervisory Nodes, Requisition Groups, and Supply Lines

The requisition workflow associates processing schedules, programs and facilities via the concept of a Requisition Group. A Requisition Group is a way to manage the replenishment process for multiple facilities or approval hierarchies. At least one Requisition Group and one Supervisory Node must be created and associated with each other in order for the requisition workflow to function. Requisition Groups can have: one to many facilities, one to many programs, one to many schedules. There are a few factors that determine if more than one Requisition Group need to be set up and they are: if multiple programs require different tiers of approvals (one to many Supervisory Node associations), and if multiple programs require a different order of approvals. 

A supervisory node is not a physical entity or location, but rather a sort of logical control point through which requisitions are routed for review and approval, and must always exist for a requisition to be approved. Supervisory nodes are thus a mechanism that OpenLMIS uses to control the workflow of requisitions. Typically, a user would be given review-and-approval rights for requisitions passing through a particular supervisory node, and these rights could be assigned for one program or multiple programs that the requisition group handles. A Supervisory Node is required for every Requisition Group so that the association creates an approval hierarchy for the requisition workflow. Only one Supervisory Node can be assigned to a Requisition Group, so if there are multiple Requisition Groups there must be more than one Supervisory Node. Also if the approval hierarchy requires an approver above the first Supervisory Node, then a parent Supervisory node must be created (Supervisory Node tree). Creating a Supervisory Node doesn't automatically enable approval capabilities until it has been associated with a user and a program.

Supervisory nodes are also used to manage and assign Supervision type rights for individual users of the system. Supervision Rights are used in a variety of situations where we'd like to give a user some capabilities within an administrative hierarchy, typically to some aspect of the supply chain focused at Facilities, divided by Program. 

Supply lines are the mechanism that OpenLMIS uses to route orders to the correct supplying facility, to be packed and shipped. Supply lines are specified on a per-program basis. Orders for all programs can be routed to the same supplying facility, or can be routed selectively, based on how your supply chain operations are structured. Orders for most programs might be filled out of a regional or national warehouse, while orders for a vaccination program might be filled out of a different facility which has adequate cold-storage capacity.



Setting up Supervisory Nodes

For each Supervisory Node, a Supervisory Node code, Supervisory Node name, Description, Parent Node, and Facility Code can be defined but not all fields are required. The Supervisory Node Code is a required field. The code is an alphanumeric identifier that is the shorthand description for the Supervisory Node and is used when CSV uploads are part of the setup process (referenced in Step #3). The Supervisory Node name is also required, and is the common name for the Supervisory Node that will be visible to the administrator when completing assignments so the name should be meaningful for the organization. The description is an optional field that can further assist in identifying the Supervisory Node purpose or responsibilities. The Parent Node is only required if the Supervisory Node needs a higher level approval to complete the approval process. The Facility Code is the facility associated with the Supervisory Node.

Example:

Supervisory Node Code (required)Supervisory Node Name (required)Description (optional)Parent Node (optional)Facility Code (required)
SN1

FP Approval pointFamily Planning approval point
HC01
SN1.1FP Approval sub pointFamily Planning approval sub pointSN1DH01
SN-CUAMBA-DISTCuamba district approval point (EPI)
Niassa province approval point (EPI)D001 - Depósito Distrital Cuamba



Setting up Requisition Groups


A requisition group is a concept that is used to tie facilities together to drive the approval process and allows for management of replenishment processes. For each Requisition Group, a Requisition Group Code, name, Supervisory Node, and description must be defined but not all fields are required. The Requisition Group Code is a shorthand for identifying the requisition group, and is used in subsequent CSV uploads of related data. The Requisition Group Name is common name for group, and will appear on various admin screens for managing requisition groups and members. It is recommended that the name be something meaningful to your organization's operations. The Supervisory Node identifies the Supervisory Node to which all requisitions from this group's member facilities will be routed. The description is for any additional descriptive information that will be helpful when setting up or managing requisition groups and members. 

Example:

Requisition Group Code (required)Requisition Group Name (required)Supervisory Node Code (required)Description (optional)
RGFP1RG Family Planning 1SN1Supports facilities running the family planning program on a monthly schedule
RGEM1RG Essential Meds 1SN2Supports facilities running the essential meds program
RGFP2RG Family Planning 2SN1.1Supports facilities running the family planning program on a quarterly schedule
RGEPI1RG EPI 1 (districts)SN-NIASSA-PROV/Niassa province approval pointNiassa province approval point (EPI)


Associating Requisition Group Programs and Schedules


Example:

Requisition Group Code (required)Program (required)Processing Schedule (required)Direct Delivery (required)Drop off Facility (optional)
RGPS1EMMPSTRUE
RGPS2HIVMPSTRUE



Setting up Supply Lines

Supply lines are the mechanism that OpenLMIS uses to route orders to the correct warehouse or facility, to be packed and shipped. Supply lines are specified on a per-program basis. Orders for all programs can be routed to the same warehouse or facility, or can be routed selectively, based on how your supply chain operations are structured. Orders for most programs might be fulfilled by a regional or national warehouse, while orders for a vaccination program might be fulfilled from a local facility which has adequate cold-storage capacity.
Supply lines for external fulfillment are specified for supervisory nodes that are at the top node of their supervisory hierarchy, because this is the point from which the orders are released to a warehouse to be filled. For local fulfillment, the supply lines may be defined at an intermediary level in the supervisory node hierarchy. Then the approval at that intermediary level is considered a final approval that will create an order to fulfill. Each supervisory node at the top of their hierarchy must have a supply line specified for each program that is supported by the requisition groups under its supervision. This includes both requisition groups under its immediate supervision, as a supervisory node only has one requisition group it directly supervises.

Example:

Program (required)Supervisory Node (required)Supplying Facility (required)Description (optional)
FPSN1WH01Ntcheu District Warehouse supplies Family Planning
Essential MedsSN2WH02Balaka District Warehouse supplies Essential Meds


In the Supply Lines list view, you are able to view the facilities that the Supervisory Node supervises by hovering your mouse over the Supervisory Node column.


(warning) Make sure the Supply Line is configured with the correct Supervisory Node. If a Supply Line is configured to a child Supervisory Node then the facility associated with that child node will not need a parent node approval. (This configuration may be desired for local fulfillment.)



Setting up Supply Partners (in progress for 3.5 updates)

(Add explanation of multiple supply partners and the need, as well as the administrator configuration screens here Nikodem Graczewski (Unlicensed))



Link to Supervisory Hierarchy diagram




Understanding User, Roles, and Rights 

Understanding Users, Roles, and Rights

A user in OpenLMIS is a person who accesses the system. A user is assigned a role(s) to control their access rights within the system. Role assignment is critical for users to have the appropriate access within the system. A Role is a combination of one or more rights available in OpenLMIS. Rights relate to individual actions that a user can take, such as view a report, or create a requisition. There are four role types already defined in the system: Supervision, Fulfillment, Reporting, and Administration.

Rights within Roles (Role Based Acess Control)

Setup Users


Setting up users requires gathering basic user information such as first and last name, email (if they have one), and what their role and access requirements are within the system.


Example:


Setup Roles


There are four role types already defined in the system that you can utilize to create roles that fit your organization's needs (Supervision, Fulfillment, Reporting, and Administration). All required Roles must be set up to ensure a role exists to assign to a user. There are three steps to setting up roles within the predefined role types: select the role type, enter role details, and select rights specific to the role.

Example:

Role Name (required)Description (required)Rights (at least one selection is required)
Delivery ApproverCan manage proof of deliveries
  • Edit orders
  • Transfer orders
  • View orders
  • Manage proofs of delivery
District Storeroom ManagerCan view and approve requisitions
  • View requisition
  • Approve requisition
  • Adjust stock
  • Authorize requisition
  • Edit stock inventories
  • Create requisition
  • Delete requisition
  • View stock cards
Storeroom ManagerCan create, view, and delete requisition
  • Adjust stock
  • Authorize requisition
  • View requisition
  • Edit stock inventories
  • Create requisition
  • Delete requisition
  • Approve requisition
  • View stock cards


Assign Roles 

Once Users and Roles setup is complete, you must now assign roles to the users.

Example: Supervision Role assignment for a user

Home Facility Supervision Role

(warning) For removal, if a user has an assigned Home Facility and associated Program and roles with the Home Facility, you are able to remove all associations by clicking the "x" in the Home Facility on the Edit User page. If you choose to proceed with this and select "Keep Roles", then the Home Facility is removed from any Supervision type roles that were assigned to that Home Facility, but the Roles are still assigned to the user. Keeping the roles may be helpful if a user's home facility has changed, but their roles at their home facility are the same. Or you may choose to "Remove all roles" which will remove the roles assigned, and you will need to assign new roles as needed.

Also, when the administrator navigates to the Roles for the edited user after selecting "Keep Roles" then the user's roles will show an error icon on the Roles page. 

See the example below of a user with a missing home facility but there are roles assigned:




Supervision Role

This example below shows that the administrator has assigned the user dsrmanager with the following roles:

  1. The first role assignment line shows that for the Program Family Planning, they have the Supervisory Node FP approval sub point of the Balaka District Hospital. This Supervisory Node is a child node per the Supervisory Nodes created above. The role is the District Storeroom Manager. 
  2. The second role assignment line shows that for the Essential Meds Program, they have the Supervisory Node EM approval point of the Balaka District Hospital. This Supervisory Node is the top node. The role is the District Storeroom Manager.
  3. The third role assignment line shows that for the Essential Meds Program, they have the Home Facility Supervision role of Storeroom Manager. This means that at the user's Home Facility, they have all rights associated with the Storeroom Manager for Essential Meds.
  4. The fourth role assignment line shows that for the Family Planning Program, they have the Supervisory Node FP approval point of the Comfort Health Clinic. This Supervisory node is the top node. The role is Program Supervisor, so the user has the rights of a Program Supervisor for the Family Planning program.


The assignments mean that the user dsrmanager can complete the following:

(warning) Users with approval type responsibilities must be assigned the Program, Supervisory Node, and Role for the facilities they supervise as described here. If a user is having trouble viewing requisitions to approve, or viewing requisitions associated with their facility, then the assignments will need to be updated in their user roles section above.


Example Supervision Role assignment for Stock Management user

By default, there will be two roles set up: Stock Manager and Stock Viewer. 

  1. Stock Manager role includes three rights: Adjust stock, Edit stock inventories and View stock cards.
  2. Stock Viewer role includes one right - View stock cards.

This example below shows the user srmanager2 has the Stock Manager role for their Home Facility.

The assignment means that the user srmanager2 can complete the following:


Example: Supervision Role assignment for Fulfillment user

Delivery Approver role includes two rights: View proofs of delivery and Manage proofs of delivery.

This example below shows the user divo1 has the Delivery Approver role for the Cuamba district approval point (EPI) Supervisory node.

This Delivery Approver role assignment means that the user divo1 can complete the following:


Example: Fulfillment Role assignment to a user

This example shows that the user wclerk1 has the Warehouse Clerk Role for the Ntcheu District Warehouse

The assignment means that the user wclerk1 can complete the following:

Example: Reporting Role assignment to a user

This example shows that the user administrator has the Reporting Personnel role. 

The assignment means that the user administrator can complete the following:

Example: Administration Role assignment to a user

This example shows that the user admin has the System Administrator role.

The assignment means that the user administrator can complete the following:

(lightbulb) The administrator can view all roles that exist in OpenLMIS and the number of users assigned to each role by going to Administration > Roles. 


Email Notifications and Opting Out

OpenLMIS supports automated notifications for workflows related to requisition, fulfillment, stock management, and cold chain equipment. These notifications are informational or require the user to log in and take action. All of these notifications are automatically configured to notify a user if they have assigned supervisory type roles for each component. Users have the ability to opt-out of these notifications during the user setup process, or on their own through their user profile page.

Allowing notifications or opting out of notifications on the user page is shown below. By selecting the Allow notifications checkbox a user will receive all notifications, and if they unselect the checkbox then they will not receive notifications. The Allow Notifications checkbox is selected by default.


Regardless of their role assignment or opting out of notifications, all users will receive the reset password notification and emergency requisition notifications. 


Example of notifications


Email Notifications related to Roles

Enabling automated email notifications for users is done by assigning the role and supervisory node. For Stock Management notifications, a Role must have the Edit stock inventories right. The admin must then assign the Role and the facility's Supervisory Node to the user, so that they will receive email notifications related to that facility. For Cold Chain Equipment notifications, a Role must have the Edit Cold Chain Equipment right. The admin must then assign the Role and the facility's Supervisory Node to the user, so that they will receive email notifications related to that facility. 

Example of Stock Management assignment:


Example of CCE assignment:


(warning) If a Supervisory Node is not assigned, then the user will not receive email notifications!


Now you have completed the set up of Users, Roles, Rights, and their assignments within OpenLMIS. 




Setup Facility FTP 





Setup Requisition & Report Template by program and facility type

Initial Setup of R&R Template

The R&R form is the Requisition & Report form that is used by storeroom managers to input stock information and request new stock. The R&R Template is the Requisition & Report template an administrator or implementer can configure that modifies the properties of the R&R form. R&R forms can be customized for each program and facility type, and there must be at least one requisition template per program. The requisition template customization includes defining which fields or data elements will be entered by the user, the display names for all fields, how certain calculations and validations are performed, the source of data for the columns, and the overall layout of the template. 

Regular vs Emergency Requisition

A regular requisition is the standard type of requisition that users will utilize to complete their requisition workflow. In order to be fulfilled, the regular requisition must be completed during the normal processing schedule. When logging in to start an R&R form, regular will be the default selection for the user.

An emergency requisition is a type of requisition that is not limited to one per processing schedule. A user can enter many emergency requisitions within a processing period. For example, if a user's requisition has already been approved and is in the last stages of the requisition workflow, they can enter an emergency to request additional stock. The requisition template for an emergency requisition has a limited amount of columns available and can not be changed using the process detailed below.

User Input vs Stock-Based

A regular requisition is considered a Stock-based requisition when the "Enable Stock on Hand to populate from stock cards" is selected, and the source for column's data has been changed from user input to stock cards. A stock-based requisition also requires the program to use Stock Management so that the data is populated from the program's stock cards.

Column Definitions

Defining the columns that appear on the R&R form will help instruct the users on how to enter in and review data. This is an explanation of the columns that can be displayed and reordered in the R&R form for each program. 


 

Icons

Explanation

Lock icon: When these fields are selected to display, they must be in the order that they appear on this page as the first, second, and third columns to define in the requisition template. They cannot be rearranged to appear in a different order.

This icon identifies any template column that can be reordered to appear in the R&R form. Reordering columns can be done by clicking on a row and moving it up or down. This will change the order that the columns are displayed in the R&Rs.

Display column: When the display box is checked, then the field will show in the R&R. When it is unchecked, it will not display. There are template validations that check whether required fields are displayed before a requisition template can be saved.

Letter icons: The letters inside the red circles are tags to identify each column and align to the Template Calculations. These icons aren't visible to general users, but are provided to help administrators follow how related columns are calculated.

Enable Stock on Hand to populate from stock cards checkbox is used when Stock Management service is active. Once this checkbox is selected the requisition template columns for Beginning Balance, Total Received Quantity, Total Consumed Quantity, Total Losses & Adjustments, and Total Stockout Days are disabled and will no longer display on the requisition form. The Stock on Hand will be populated by stock cards and is uneditable by the user completing the requisition form.

Label column: The text in this field is the display name for this column in the R&R and is a free text field. All Labels can be edited to match a specific program. A suggestion is to abbreviate the labels so the R&R form appears more compact for the user.

Definition column: The text in this field should explain to the user what the Label is and how it is calculated or defined to assist the person creating or reviewing the R&R. When the user is completing the R&R form, they can hover over this column label to better understand what it's used for in the R&R form. This is helpful if the label has been abbreviated to shorten the R&R form.

Source column: The source is either Reference Data, User Input, Calculated, or Stock Cards.

  • Reference Data indicates that OpenLMIS will populate the column with data from the database.
  • User Input indicates the user will enter data.
  • Calculated indicates OpenLMIS will calculate the column based on user input and reference data.
  • Stock Cards indicates that the column is populated from the Stock Management service stock cards.
Additional OptionsAdditional Options: These are additional options associated with the Source column. Tags, hiding skipped line items, and new patient count are some examples of additional options configurable in this template column.

Tags

Tags are only available to select if :

  • The template is configured to Enable Stock on Hand to populate from stock cards.
  • The Source data is selected as Stock Cards.
  • The same Tag cannot be used for multiple requisition template columns. 
  • If a Tag is available to select, it is required to select a tag to allow saving the requisition template.
  • A Tag allows mapping columns to the stock adjustment reasons from the Stock Management service. This means that administrators can specify which adjustments in the Stock Management should participate in which requisition columns.


Configuring a new Requisition Template by Program

OpenLMIS supports multiple requisition templates per program, per facility type. This configuration is helpful when a health facility may be required to report more data than a district or regional store. Once a new program is created and the facilities are associated with the new program, then the requisition template is ready to configure. 

The new requisition template must include the following fields:

After clicking Create Template, the new requisition template is populated with all available requisition template columns by default.

Before editing column descriptions and the order of each column in the requisition template, you will need to understand the dependencies and calculations of each field that is detailed below.



R&R Requisition Template Column Dependencies and Calculations (in progress for 3.5 updates)

Within the R&R template there are fields that have system generated calculations or options to change the source. Understanding how these calculations affect the workflow for each R&R template will assist in determining which sources should be used for each program. 

*Are required fields, however implementers can choose which are user input or calculated. This requirement began at version 3.2.0.

Field Label

Letter Icon

Business Definition

Calculation (Columns are identified by letter icons)

Source/Options

Template Save Validations


Allows tags

Regular Requisition Form Validations


Emergency Requisition Form ValidationsStock- Based Requisition Form ValidationsAdditional Options
SkipSAllows user to skip R&R for a product line item and hide skipped line items in the R&R formNot ApplicableNot Applicable
  • Must be in the first position/column, order cannot be changed.
  • Not required to display
NO
  • Cannot skip product if there is any data in any column (based on a previous R&R or entered by a user)
Not Applicable
  • Cannot skip product if there is any data in any column (based on a previous R&R or entered by a user)
  • Selecting "Disable Skipped Line items" will still display skipped products in the requisition product grid. 
  • Selecting "Hide Skipped Line items" will hide any skipped line items in the requisition product grid so the user doesn't see products they have already skipped. The user will need to select "Add Products" to add them back to the requisition product grid.
Product CodeOUnique identifier for each commodity/product.Not ApplicableReference Data
  • Must be in the second position/column, order cannot be changed.
  • Not required to display
NO



ProductR*Primary name of the product.Not ApplicableReference Data
  • Must be in the third position/column, order cannot be changed.
  • Required to display
NO



Beginning BalanceABased on the Stock On Hand from the previous period. This is quantified in dispensing units.= SOH from the previous period's requisitionSystem Generated
  • Not required to display 
NO
  • Users can modify the pre-populated quantities
  • Only positive numeric integers allowed
  • If C and E are user input, then the Beginning Balance will need to equal C - B - E (+/-) D or an error will be produced when submitting.
  • Column not available
  • Populated by Stock on Hand
  • Users cannot edit quantities
  • Not required to display

Total Received QuantityB*Total quantity received in the reporting period. This is quantified in dispensing units.
User Input
  • If C and E are user input, this is required to display
  • If B source is Stock Cards then it is not required to display
YES
  • Only positive numeric integers allowed
  • If C and E are user input, E = A + B (+/-) D - C
  • Column not available
  • Populated by Stock Cards
  • Users cannot edit quantities
  • Not required to display

Total Consumed QuantityC*Quantity dispensed/consumed in the reporting period. This is quantified in dispensing units.If calculated, C = A + B +/- D - EUser Input or Calculated
  • If C is calculated, E cannot be calculated
  • If C is User Input, E can also be User Input
  • If C is calculated, B is required to display
  • If C source is Stock Cards then it is not required to display
YES
  • If C and E are user input, E = A + B (+/-) D - C
  • If calculated, cannot be negative - error message
  • If User Input, only positive numeric integers allowed
  • Column not available
  • Populated by Stock Cards
  • Users cannot edit quantities
  • Not required to display

Total Losses & AdjustmentsD*All kind of losses/adjustments made at the facility.

User Input

(Source is list of Adjustment Reasons configured in Stock Management)

  • Required to display unless source is Stock Cards
NO
  • In the modal, the sum of the losses and adjustments is shown on the requisition column D. So if C and E are user input:
    • A + B - C + D = E
      • When the sum of D is positive
    • A + B - C - D = E  
      • When the sum of D is negative
  • In the modal, the user can only input positive numbers because when the reason is selected, the system determines if the number is negative or positive
  • Column not available
  • Populated by Stock Cards
  • Users cannot edit quantities
  • Not required to display

Stock on HandE*

Physical count of stock on hand, as of the requisition's processing period end date. This is quantified in dispensing units.


A + B (+/-) D - CCalculated, User Input, or Stock Cards
  • If E is calculated, C cannot be calculated
  • If E is user input, C can also be user input
  • If E source is stock cards then it is not required to display
NO
  • If User Input, only positive numeric integers allowed

Column not available

  • Populated by Stock Cards
  • Users cannot edit quantities
  • Not required to display

Calculated Order QuantityI
H - ECalculated
  • If I is displayed, I is the default reorder number unless an amount is entered into J or K
  • If displayed then A, B, C, D, E must be displayed.
  • If displayed then P, N, X are not required to be displayed
  • Otherwise it is not required to display


NO
  • Must be positive numeric number, or error will display in columns A, B, C, D, or E

Column not available

Updates to this column validation must be added for 3.5 Sebastian Brudziński
Requested quantityJRequested override of calculated order quantity. This is quantified in dispensing units.
User input
  • If J is displayed, W must be displayed
  • Otherwise it is not required to display
NO
  • Only positive numeric integers allowed
  • If left blank, column I, Calculated Order Quantity, will be used to calculate the Total Requisition Cost and Packs to Ship
  • Only positive numeric integers allowed
  • J will be used to calculate the Total Requisition Cost and Packs to Ship
  • Required to display
  • Only positive numeric integers allowed
  • J will be used to calculate the Total Requisition Cost and Packs to Ship
  • Not required to display

Requested Quantity ExplanationWExplanation of the request for a quantity other than the calculated order quantity.
User Input
  • If J is displayed, W must be displayed
  • Otherwise it is not required to display
NO
  • If J contains data, this column must have some data.
  • Only text allowed
  • Required to display
  • Only text allowed


Number of New PatientsFNumber of New patients data
User Input
  • Can either be New patient count or Dispensing units for new patients
  • Not required to display
NO
  • Only positive numeric integers allowed
Column not available

Approved QuantityKFinal approved quantity. This is quantified in dispensing units.
User Input
  • If only I, or J and W are displayed, then K must display for users with Approve rights
NO
  • If only I is displayed, then K is auto-populated with values from I.
  • Users can modify the pre-populated quantities
  • Only positive numeric integers allowed
  • Auto-populated from J
  • Users can modify the pre-populated quantities
  • Only positive numeric integers allowed
  • Auto-populated from J
  • Users can modify the pre-populated quantities
  • Only positive numeric integers allowed

RemarksLAny additional remarks
User Input
  • Not required to display
NO
  • Not required
  • Any text input allowed
  • Not required to display
  • Any text input allowed
  • Not required to display
  • Any text input allowed

TotalYTotal of beginning balance and quantity received.A + BCalculated
  • Not required to display
NO
Column not available
  • Not required to display

Total Stock out DaysXTotal number of days facility was out of stock.
User Input or Stock Cards
  • If N is displayed, X must be displayed
  • If X source is Stock Cards then N must be displayed
  • Otherwise it is not required to display
NO
  • Only positive numeric integers allowed
Column not available
  • Not required to display

Adjusted ConsumptionNTotal consumed quantity after adjusting for stockout days. Quantified in dispensing units.

Roundup(C * (M * 30) / ((M * 30) - X ))) 

M = Number of periods to average (this is identified in the additional options column for P)

Calculated
  • If N is displayed, X must be displayed
  • If Z is displayed, the N must be displayed
  • Otherwise it is not required to display
NO
Column not available

Averaged ConsumptionPAverage consumption over a specified number of periods/months. Quantified in dispensing units.

AMC (P) = (Nt0 + Nt-1 + Nt-2) / 3

Last "t" periods averaged (includes the reporting period being input)

Calculated or Stock Cards
  • Number of periods must be greater than or equal to 2
  • If P is displayed then N and X must be displayed, otherwise N is not required to display
NO


  • Column not available
  • If user is completing an Emergency Requisition, the values shouldn't impact avg consumption calculations for regular requisitions.
Updates to this column validation must be added for 3.5 Sebastian BrudzińskiNumber. of periods to average
Maximum Stock QuantityHMaximum stock calculated based on consumption and max stock amounts. Quantified in dispensing units.P * MaxPeriodStockCalculated
  • Not required to display
NO
Column not available
  • Not required to display

Price Per PackTPrice per pack. Will be blank if price is not defined.
ReferenceData
  • Not required to display
NO
Column not available
  • Not required to display

Packs to ShipVTotal packs to ship based on pack size and applying rounding rulesJ / UCalculated
  • Not required to display
NO
  • If J or K contains no data, then I is the default reorder amount and is used to calculate packs to ship.
  • If J contains data and K does not contain data, then J is used to calculate packs to ship.
  • If K contains data then it overrides any data in I or J, and K is used to calculate packs to ship
Column not available
  • Not required to display

Total CostQTotal cost of the product based on quantity requested. Will be blank if price is not defined.V * TCalculated
  • Not required to display
NO
  • This column updates as I, J, or K are updated
  • If K contains data then it overrides any data in I or J, and then K is used to calculate total cost
  • This column updates as J or K are updated


Dispensing UnitUDispensing unit for this product.
ReferenceData
  • Not required to display
NO
  • Column not available
  • Not required to display

Ideal Stock AmountGThe Ideal Stock Amount is the target quantity for a specific commodity type, facility, and period.
ReferenceData
  • Column not available
NO
  • Column not available


Additional Quantity RequiredZ

Additional quantity needed for New Patients or other factors such as seasonality

Adjusted Consumption (N)+ Additional Quantity Required (Z)



  • If Z is displayed, then N is required to display







Manage/Edit R&R Template

Once a template has been created and is in use, it can still be modified and updated to better support the programs and users. There are some important considerations you should know before making changes to the template:

Configuring Requisition to Hide Skipped Products

The implementer or administrator has the ability to allow hiding products that have been skipped in requisitions. This is a helpful configuration that shortens a requisition form when the same products are frequently skipped. 

In the requisition template, in the Skip column, select from the Additional Options dropdown "Hide Skipped Line items".


Once skipped line items has been configured in the requisition template, the user will no longer see skipped products in their requisition form. They can choose to add products that are skipped back into the requisition form if necessary. 


Setup Order File


Order File format


UI Fields
Displayed in PDF or Orders UI
Labels in Order File
Source
Order Number/CodePDF, UIOrder NoOrder Number Prefix (if any) + Program Code (if set to True) + R&R type suffix (if set to True)
Order StatusUI

ProgramUI

Date CreatedUI

Date Last UpdatedUI

Last UpdaterUI

Requesting Facility NamePDF, UI

Requesting Facility TypePDF, UI

Requesting Facility CodePDF, UI

Order Emergency FlagUI

Product CodePDF, UIProduct CodeProduct Code
DescriptionPDF, UIProduct Name
Ordered QuantityPDF, UIOrdered Quantity

1 is the Approved Quantity (ApprovedOrderQuantity) and 2 the Requested/CalculatedOrderQuanity (OrderedQuantity),

Displayed in Packs

Dispensing UnitsPDF, UIDispensing Units


Order file Name

Order file is generate with name ‘O’ + order number.csv

Validations

  1. One order file generated per Requisition
  2. Quantity Ordered = Packs to Ship
  3. Any product with Quantity Ordered as zero is excluded from the file
  4. If Quantity Ordered for all product in an order is zero no file is generated



Setup CCE Catalog

In order to use the CCE Management features in OpenLMIS, you will need to first set up the CCE Catalog. The catalog is a list of CCE devices stored in the back end, along with other relevant information about the equipment. The catalog provides a list of devices that a program user can select from when they are adding specific device information to a facility. The catalog is created in the system through uploading a CSV. This CSV must be in the correct format, otherwise the system will not accept it as a valid catalog. More information on configuring the CSV CCE Catalog is available in the "Configufin Cold Chain Equipment catalog" section in Step 3: Configuration via CSV uploads.

Catalog Template Download

The catalog template CSV is already loaded into the system as the default CCE catalog. You will need to download the template so that you can add your own devices to the CSV and upload them to be visible to users in the system.

To download the catalog template CSV, go to CCE Management > CCE Catalog. Click "Download current catalog." This will download a CSV file that can be used as a template for your CCE Catalog. If you already have an Excel or CSV file of a CCE Catalog that you'd like to use, you must transfer the data into the OpenLMIS CCE Catalog template. You must retain the same column headers from the downloaded catalog template. If you delete or change any column headers in the template, you will not be able to upload the CSV as your new CCE Catalog. 


Setup Google Analytics tracking

OpenLMIS integrates with Google Analytics in order to provide insights into platform traffic and user behaviour. In order to benefit from this integration, start with creating a Google Analytics account here: https://analytics.google.com/analytics/web. Once that's done, you should find your Google Analytics tracking code. Go to Admin settings on Google Analytics and find section called "Tracking Info". This section will show your unique Tracking ID as shown below.



The Tracking ID needs to be provided to your UI project (equivalent of https://github.com/OpenLMIS/openlmis-reference-ui) during build time. It can be achieved in two ways:


Once built and deployed to your server, the tracking should be in place. and you should be able to see the metrics in the Google Analytics account you created. For any issues with Google Analytics, you can check their help center: https://support.google.com/analytics

In addition to the regular metrics in place, the OpenLMIS instance will also send button click events to the Google Analytics. You can also implement and send your own events. The UI in the offline mode will collect the page views and events and send them as soon as the instance is back online.

Step 3: Configuration via CSV uploads

Configuring Cold Chain Equipment catalog (if CCE service is used)

How to fill in CSV files to import CCE data:

You can find CSV templates, containing only headers, to upload CCE data here. In order to create Catalog Item with only mandatory fields use mandatoryFields.csv. Template with all fields is allFields.csv. Of course you can create your own template that contains mandatory fields and some of the non-mandatory fields. The possible values for fields are:

  1. From PQS catalog (values are not case-sensitive):
    1. any of: "1", "true", "t", "y"
    2. any of: "0", "false", "f", "n"
  2. PQS equipment code: any text
  3. Type: any text
  4. Model: any text
  5. Manufacturer: any text
  6. Energy Source: 
    1. ELECTRIC
    2. SOLAR
    3. GASOLINE
    4. NOT_APPLICABLE
  7. Date of prequal: 4-digit year

  8. Storage Temperature: values from MINUS20 to MINUS1, ZERO, from PLUS1 to PLUS4 
  9. Max operating temp (degrees C): any number
  10. Min operating temp (degrees C): any number
  11. Energy consumption (NA for solar): any text
  12. Holdover time (hours): any number
  13. Dimensions: triple in format: "x, y, z", where x, y and z are any number for Width, Depth, Height respectively
  14. Visible in catalog (values are not case-sensitive):
    1. any of: "1", "true", "t", "y"
    2. any of: "0", "false", "f", "n"

For all fields you need to keep rules. Mandatory fields are bolded.

There will need to be an identifier for each item. If there is a PQS code, use that; otherwise, use a combination of make type and model as the unique identifier.




Step 4: Verify your configuration 

OpenLMIS includes a set of four reports that will help you verify the system has configured correctly. The reports are listed below. You must be logged in with a user account that has been assigned a role which includes the rights to run each of these reports. 


1. Facilities Missing a Create Requisition Role: This report will identify any facility where a program is operating but there is no active verified user who has been assigned a role that includes the rights to create requisitions for that program. The role must be assigned to a user for whom the facility is their home facility, or to a user has been assigned the role at a supervisory node over the facility. If no user holds this role, it will not be possible for the facility to create and submit requisitions for the program
2. Facilities Missing an Authorize Requisition Role: This report will identify any facilities where a program is operating but there is no active verified user who has been assigned a role that includes the rights to authorize requisitions for that program. The role must be assigned to a user for whom the facility is their home facility, or to a user has been assigned the role at a supervisory node over the facility. If no user holds this role, it will not be possible for the facility's requisitions for the given program to be authorized, and then advance for review and approval.
3. Facilities Missing an Approve Requisition Role: This report will identify any facilities where a program is operating but there is no active verified user who has been assigned a role that includes the rights to approve requisitions for that program. The role must be assigned to a user for whom the facility is their home facility, or to a user has been assigned the role at a supervisory node over the facility. If no user holds this role, it will not be possible for the facility's requisitions for the given program to be approved, and eventually get released as an order.




Step 5: Customizations 

Configuring message strings

Translations: Transifex

Messages

Messages are translateable pieces of content that are a part of the OpenLMIS-UI. The best way to update a message is by configuring the OpenLMIS-UI to use your implementation's Transifex settings and editing the message directly in Transifex. What Transifex does is replace a message key, which is defined in the UI, with a human readable message. This is how the OpenLMIS-UI supports multiple languages.

See the example below:

<!-- HTML similar to this, will be updated by Transifex once the OpenLMIS-UI is built and run in a browser --> <p>{{ 'example.instructions' | message }}</p> <!-- The above message will be displayed to a person using the OpenLMIS-UI as: --> <p>These are some instructions</p>

The strategy in the OpenLMIS-UI is to not reuse specific message keys, and let the tools in Transifex group messages that are the same together into a single spot for translation. This allows an implementer to further customize small messages such as 'Search' to 'Search Facilities' if the needs of their implementation require more specificity.

If there are large message string changes, it is possible for an implementer to replace the messages_en.json file, and make the changes that are needed. This is possible as a last resort but not recommended.


Configuring Time Zones

A timezone may optionally be associated with the TIME_ZONE_ID property in a distribution's .env configuration file.

Customizing order numbers

The default implementation generates 8 digit, base36 numbers. It can be customized using an extension point:

  1. Create an extension. See an example here. Include fulfillment service with version >6.0.1 as a dependency in build.gradle:

    dependencies { 
    	compile "org.springframework.boot:spring-boot-starter-web" 
    	compile "org.openlmis:openlmis-fulfillment:6.0.1" 
    }
    


  2. Within the extension module, create a bean that implements OrderCodeGenerator interface. Annotate it with some id, e.g. YourCustomizedCodeGenerator

  3. Create a docker image that holds your implementation's extensions. See this example. 

    Add your extension as a dependency in build.gradle and configure it in extensions.properties like so:

    OrderCodeGenerator=YourCustomizedCodeGenerator
    

    Note: The value has to match bean id.

  4. Follow this section to configure your distribution to load the extensions.

Configure Proof of Delivery Report

OpenLMIS provide a means for a customer to use their own template for the Proof of Delivery Report. The template customization includes use of all data elements that are available while preparing the template with Jaspersoft Studio. For detailed instruction about how to create/modify Reports, see the Jaspersoft Studio user guide. To add fields you need to register them from sql query. You can use tables from schemas fulfillment and referencedata. There is an assumption that both schemas are in the same database. Changing the template also requires using software development tools like Curl and/or Postman. If you are not familiar with these tools, you may need to request support from a developer to upload the new report template into OpenLMIS.
Available Parameters to use in your .jrxml template that are defined by OpenLMIS fulfillment service are: format (e.g. "pdf"), REPORT_LOCALE (current locale), REPORT_RESOURCE_BUNDLE (resource bundle for locale with messages), subreport_dir (points to reports folder in fulfillment service resources), image_dir (points to folder with images in fulfillment service resources), pod_id.
Available Resources can be found in OpenLMIS Github repository.

The default Proof of Delivery Report built into OpenLMIS uses podPrint.jrxml that can be found in Github repository. To change it to a custom template, call "multipart/form-data" POST request for endpoint /api/reports/templates/fulfillment with the following in the body:

The access token will be necessary for user with right REPORT_TEMPLATES_EDIT.

Example request using curl: curl -i -X POST -F "file=@/some/path/podPrint.jrxml" -F "name=Print POD" https://test.openlmis.org/api/reports/templates/fulfillment?access_token=64d046f-c4b5-49fe-842e-5a5b049699f5

Example request using Postman:

Configuring report images

Some reports contain static images, such as a logo to appear at the top. In order to add or customize an image in a report, a user has to upload it by making a POST request to the /api/reports/images endpoint with the following in the body:

Example request using Postman:

After the image has been uploaded, you can reference it in report's template by adding a parameter with its name. The type has to be java.awt.Image and isForPrompting set to false.

<parameter name="example-image" class="java.awt.Image" isForPrompting="false"/>

The image element (generated by JasperReports Designer) looks like this:

<image>
  <reportElement x="20" y="10" width="130" height="60" uuid="50f2c4e9-d19d-4264-887d-0645674af6d1"/>
  <imageExpression>
    <![CDATA[ $P{example-image} ]]>
  </imageExpression>
</image>

For instructions on how to customize report's template, see previous section. 

Note: When uploading the template, use the endpoint from the openlmis-report service: /api/reports/templates/common

Adding new Jasper Reports

It is possible to define custom Jasper reports and get them to show up on the UI by uploading Jasper source files (.jrxml) to the API. In order to do so:

  1. Design a Jasper Report using a SQL dataset. You can use all the database schemas that exist in OpenLMIS and the data source will be automatically populated on runtime.
  2. If you want a parameter to show up as input or a dropdown, you need to provide a couple of properties. In order to do so in Jasper Designer, open up parameter's details, select Advanced tab and edit Properties

    Required properties:

    Optional properties:

  3. Upload your report to the API by making a multipart/form-data POST request to /api/reports/templates/common

    An access token with REPORT_TEMPLATES_EDIT right is required to make that request.

  4. Your report should show up under Reports → View Reports tab:



Manage Service Accounts

OpenLMIS allows for integration with external partners by using service accounts that are managed by the administrator. The administrator must generate a new API Key by clicking Add, and the system will automatically generate a key to provide to the external partner manually. API Keys do not expire, and require the administrator to remove them by clicking Delete. The Service Accounts table will display all API Keys, with the most recent at the top of the table.






Reporting Configuration