-
Notifications
You must be signed in to change notification settings - Fork 2
Technical_Documentation
Technical Documentation - openLMIS July, 2011
This document is intended to provide an orientation to the developer or system architect.
vrMIS3 was developed in several “developer sprints” with different targets (requirements) between October 2009 and April 2010. The two main targets for development were DEMO and MZ-PRODUCTION. In April 2010, vrMIS was reconfigured as an “instance” of openLMIS, whereas openLMIS was released as opensource. The code differences between vrMIS3 and openLMIS mostly consist of localization and configuration files. The MZ-PRODUCTION version of vrMIS3, as a “version” of openLMIS was a released to the field in October 2010.
As a starting point, the concepts, user interfaces, and high level requirements for vrMIS3 were derived from requirements for vrMIS2, which was pushed into production in March 2009. vrMIS2, a dot net application on SQL runtimes, contained several data model inconsistencies as was discontinued in late 2009. vrMIS3 represents a mixture of concepts aimed at solving the “last mile” of data collection for public health, and to a large extent, specifically for logistics and service delivery support.
From now on, I will refer to OpenLMIS, although all comments are equally applicable to vrMIS3.
OpenLMIS includes concepts such as health units, warehouse pickup, cold chain monitoring, delivery quantities, stock outs, ideal stock amounts, data completeness, immunizations administered, and delivery routes. It also includes multiple modes for getting data into and out of the internet based application.
OpenLMIS is neither a transactional system, nor a clinical system, nor a medical records system, nor a facility based system, nor is it a laboratory system. Instead, it is a tool for the public health sector in low resource settings (developing countries) countries to manage the volume of data points into a useful information set. Where other systems have failed to reach the end of the dusty road because of a lack of computing infrastructure, openLMIS expects to be there. Conceptually, it is strongest in knowing how to count or tally a set of things so can be extended to many other items, such as bednets delivered or incidence of disease.
OpenLMIS - Open Logistics Management Information System could just as easily be named “Last Mile Information System” It is found at https://github.com/villagereach/openLMIS
Architecture (see also Architecture )
OpenLMIS is a M-V-C application written in Ruby on Rails with some additional external components. The majority of the project consists of the Rails app. The backend database is currently mySQL by default, although some effort has been made to move to Postgres. Postgres is recommended as a target.
The following diagram explains the high level components:
HTML5 front end (Tested on Firefox 3.6) Aside from the typical web application, there is an HTML5 front end, which is built out for the specific use cases for VR’s Mozambique program, i.e. for the MZ-PRODUCTION target. The HTML 5 essentially duplicates the code found in the main field visit forms and includes some reports as well. It makes use of key-pairs and javascript libraries for binding the key-pairs to the data structure. At the time of code implementation, no other data storage was considered stable. Xforms were considered as a front-end /offline technology but implementing the xform libraries with HTML5 proved highly difficult to troubleshoot and prone to undocumented issues.
Mobile front end: SMS and ODK For the DEMO target there are also two other front end components that have been built, tested, and demo’d in various fora. The SMS component is built to allow text messages to update the status of the refrigerator, which is an object modelled as a simple inventory with a current status attribute. The ODK integration allows for specific named delivery routes to submit the delivery data for one health unit at a time within the delivery route.
I18N support A plugin is used to provide internationalization and most display and report labels and menu items are found in the application configuration folder in both English and Portugese.
For working on the vrMIS3 code, there is a complication arising from the MZ-PRODUCTION target being an instance of the OpenLMIS code base. Specifically, the vrMIS3 project (managed by VR) uses the git modules mechanism - please be sure to consult with the git manuals as this can be non-intutive.
If you are using vrMIS, then your code must manage the submodules, specifically:
[submodule "vendor/plugins/olmis"] path = vendor/plugins/olmis url = git://github.com/villagereach/openLMIS.git [submodule "vendor/plugins/report"] path = vendor/plugins/report url = git://github.com/joelhoffman/report.git [submodule "vendor/plugins/referenced_by"] path = vendor/plugins/referenced_by url = git://github.com/joelhoffman/referenced-by.git [submodule "vendor/plugins/i18n_backend_database"] path = vendor/plugins/i18n_backend_database url = https://github.com/dylanz/i18n_backend_database
Note that the openLMIS.git is treated as a vendor plugin to the project. This is a rails convention to use a vendor plugin for a set of code that is likely to change and may need to be updated during the development of the overall application. A future direction would be to create a Gem (gemify) the openLMIS plugin so that it is openlmis.gem, or to change the approach, such that the configuration files are changed at the time of deployment, rather than kept in the code repository. TBD
Where is the code?
Github.com, specifically https://github.com/villagereach/openLMIS/ is where the code is hosted for openLMIS. For the vrMIS3 version and configuration, a small amount of code is hosted on the private hosting at Unfuddle. Anonymous access is allowed only for the openLMIS codebase.
See the Demo Script in the appendix for a narrative version of this.
Most frequently used by the field in operations:
Offline: Login to offline version by Field_Coordinator
Offline: Field Coordinator enters all of the data from the paper form which consists of several sub-forms.
Offline: Upload the completed forms.
Login and change language (english | portugese).
Login as Field Coordinator or Supervisor and View the completeness of the data - based on unit of one Paper Form per Health Unit per Month.
As Field Coordinator or as Supervisor, View the reports corresponding to the data found in the forms.
As Field Coordinator or as Supervisor, Export the data from the reports page to excel.
Less frequently used:
Add a new refrigerator to the inventory
View the status of all refrigerators for a Province. (DEMO target)
Change the ideal stock amount for a health unit (aka clinic)
Not supported or not fully supported in the UI:
CRUD operations for a health unit
CRUD operations for a delivery route
CRUD operations for a user.
The model and controllers follow from these general concepts.
CONCEPT --> Definition
-
Acts as Tally In openLMIS we care about counting different things, such as vaccines delivered or vaccines administered. Acts as Tally should never appear in the UI. It is referenced in the models such as
-
Adult_vaccination_tally.rb, epi_usage_tally, etc. Generally any data point that is not part of the monthly inventory in the stock room is treated as a tally.
-
Cold Chain A cold chain consists of each step along a distribution network where the vaccines are kept at proper temperatures. In the system, we model this as a listing of refrigerators at each location.
-
Cold chain or Refrigerator status Each refrigerator is like an inventory object, with static attributes, and a “status log” or “service log”. Static fields include the mobile number of the associated clinic staff. Messages received from that mobile number show up in the status of the first (usually only) refrigerator associated with the health unit. See Fridge in the controller and models. A Fridge is associated with a stock room.
-
Data source ODK, offline, xforms - the infrastructure exists to accept data from different external sources. This is meant to allow for a set of web services interfaces.
-
Deliveries Deliveries of supplies and medical commodities.
-
Delivery Route A convenient way to organize the Field Coordinator work. Each delivery route consists of a set of Health Units that should be visited each month. In the data model, a delivery route consists of a set of health units (locations) and a field coordinator belongs to the delivery route. A delivery route is created at configuration time or can be updated by a system admin. Delivery route is also used to define the data scope that a field coordinator may edit.
-
Excel visit data This is legacy code. At one point the design was to allow for excel workbooks to be the offline data entry tool with regular uploads possible. The strategy switched to xforms, and then to a more straightforward (but cutting edge) use of HTML5 data cache and “offline”.
-
Field Coordinator The primary user of the system is the field coordinator who is doing the data entry. The system is geared to monitoring the data entry for each field coordinator on a delivery route.
-
Field officer Data Completeness This is specific to the application and the work flow we are monitoring. Each month at each health unit (aka clinic) there is an expected datasheet form that should be filled out. This is a simple metric of % complete.
-
Health Unit The smallest unit for which data is collected. Each health unit is assigned to a Delivery Route.
-
Ideal stock This is a confusing concept. Ideal stock is the level of stock of a particular commodity or vaccine that should be maintained at each health unit. However, it has also come to mean the amount that should be taken to the health unit because the expectation is that a health unit goes through its entire stock on hand in a month.
-
Indicators A health service name for calculated report elements that express something about the “health” of the health system service. Indicators are report elements such as stock outs and coverage rate. Indicator reports are thus reports that include specific ratio and trend calculations.
-
Inventory The concept of inventory is applied to the health units (delivery points on the delivery route) but not to the Warehouse at the provincial depot.
-
ODK OpenDataKit – this is a project at the UW which has received substantial support from various funding agencies and is now in widespread use as a survey and professional data collection tool. ODK Collect implements an xForms interface on the Android phone and allows for data upload. OpenLMIS has an xml parser for various xforms that relate to deliveries and inventory items.
-
Offline To allow for data entry in poorly connected locations, openLMIS has a separate module that duplicates the forms found in the Rails app. These are essentially html forms and for data storage, the HTML5 data caching is used.
-
Package There is a concept of packages containing multiple items of the same type. This relates to inventory data.
-
Pick up from Warehouse The workflow this is intended to support consists of generating a list of expected amounts (ideal stock) to take on a delivery route, and then an actual set taken from the Warehouse (at the Provincial Depot level).
-
Province and District Each Health Unit belongs to a District and Province for administrative reasons. This administrative hierarchy is mainly used for reporting functionality.
-
Signature
-
A signature is required on each health unit form and who signs is important.
-
SMS update The SMS update is currently permitted for the cold chain, i.e. each refrigerator status may be updated. SMS update may also be extended to stock out levels or stock out events.
-
Stock outs When the inventory is noted as being zero, this counts as a stock out event.
-
Supervisor Another key user, the supervisor interfaces are meant to convey more information about the status of the data and the health unit performance based on the scope of supervision. Typically there is at least one supervisor per Province. The typical scope is also at the Provincial level – i.e. all delivery routes in a Province would be included.
-
Warehouse There is a label “warehouse” that appears in the UI but is modeled as a location with a stock room. Each health unit may have a stock room. Other locations may include District Hospitals or Provincial Depots. i.e Stock rooms may also be at other levels of the public health Adminstration hierarchy.
For the VR DEMO deployment there is an SMS plugin – MEC licensed sms plugin that creates a connection to clickatell. The Clickatell gem, which already exists is only one-way MT (mobile terminated). The MEC SMS Plugin provides round trip. (MO - mobile originated) Message handling was moved out of the SMS Plugin to be part of the command processor (in Lib/command_processor).
Release group A
Branch the codebase from vrMIS3_Moz and clean up configuration tables.
Separate out vaccination and cold chain user interfaces
Implement Postgres and deploy to Heroku for easy deployment mechanism
Redesign form mechanism to handle hundreds of potential commodities - i.e. views that allow for tab driven data entry and auto filled fields
Generalize the configuration mechanism for commodity tracking to enable ease of deployment for multiple commodities
Replace reports with external toolset or gemset
Release group B
Implement order fulfillment feature with existing paper forms to automate process from field request
Track movement of commodities from stock room to stock room for stronger inventory/storage control
Build out reporting mechanism to be consistent with SDMX standard and export to openDHIS
Add additional UI component additional commodity tracking online and offline
Design linkage with openMRS via pharmacy sub-system component and implement prototype (leverage existing)
Release group C
Create configuration UI or wizard to enhance ease of deployment
Design and implement sub-components within an overall software framework to enable greater separated evolution
Strengthen data completeness and accuracy measurements in reports and real time displays
Strengthen cold chain storage management with additional inventory and repair process support
Release Group D
Add ordering/requisition and strengthen order-fulfillment automation
Add simple dispatch and transport assignment features
Implement pharmacy system sub-component for full administering/dispensing integration
Implement unique item level tracking with bar codes or RFID utilizing G1 logistics standard
Generate sub-ledger accounting entries for integration with upstream systems
Release Group E
Build higher transaction volume level support
Enable integration with enterprise applications at national and sub-national levels
Create transport tracking and automation systems for optimizing dispatch
Create real time audit alerts and additional features around overall system performance
Leverage standards such as G1 and strengthen integration with other logistics systems
Build on existing features
module ActsAsStatTally
Reports Building reports are complicated by the fact that the system is looking at tally’s of various things, irrespective of their notional relationship. That is, each count of something is treated as a separate tally, so that a delivery count may not have any explicit relationship with an administered tally. The system is non-transactional in this way.
Demo Script
Updated: May 26th, 2010
This is a short demo script of a single VRMIS feature and a longer in-depth demo of a cross-section of the VRMIS functionality.
PHONE to APPLICATION DEMO SCRIPT (~5 minutes):
I'm going to show one of the data collection methods supported by openLMIS in this quick demo on my smart phone (Presenter Note: show phone in hand).
Using ODK (Open Data Kit) Collect software, openLMIS has the ability to receive forms based data capture via smart phones running the Android operating system.
To start this demo, I am going to launch the ODK Collect application by clicking the icon on the dashboard of my smart phone.
(Presenter note: launch app)
Now in the main menu, I am going to click "Enter New Data" to access the list of forms available on this particular smart phone. As you can see, there are mutliple forms already loaded into this form which can be filled out and uploaded to our web server.
I am going to demonstrate the data entry process on our sample form. So, I will scroll down to this form (currently called TestForm3 form) and click on it.
A cover page will load and I swipe my finger from right to left (imitating turning pages with your finger) to advance to the beginning of this form. This form is intended to be collected by a distributor or a supervisor while visiting a health unit. This sample form represents a subset of the data collection points expected at an SDP.
After swiping, I am now on the first question of this form represents a text field which asks for the health center's name.
(Presenter note: try to advance with entering a name)
If I try to advance to the next page without recording a response, an error message is prompted saying that this answer is required. Each question can be individually configured to be required or not.
(Presenter note: enter in "SDP")
After entering in the name of the health center, the next question asks for the date representing another data field available on ODK Collect.
(Presenter note: change day in date, then advance)
Next question, this refrigerator question shows the radio button or single select data field available.
(Presenter note: select one and advance...continue to advance through the form with small narrative about the data points)
Once I am done entering information into the form, I can either "Save as Incomplete" or "Save as Complete". I will save as complete because I have fully filled out the form.
(Presenter note: select save as complete)
Now back on the main page, I can send the data I just entered. I'll select the form that I just filled out and then click "Send Selected File(s)".
(Presenter note: select the form from the list and click send.)
This form is now being sent up to our online application. So, let's go see this data.
(Presenter note: toggle to web browser (which should already be loaded) with vrMIS3 online application open.)
On this online dashboard, I can see the most recent data that has been uploaded or entered. Since I just uploaded that form,
ODK Collect enables professional data collection for health professionals.
SHORT DEMO SCRIPT (~5 minutes):
I'm going to show you a key aspect of the vrMIS functionality in this quick demo.
We'll start with logging into the site mis3.villagereach.org as the field coordinator.
Reports – Google Maps
An important component of managing the information is to being able to visualize and share it. We've leveraged google maps and other open source tools.
(click on "View Reports" tab)
There are currently 6 categories of reports: Field Coordinator Efficiency, Delivery Intervals, EPI Vaccination Report, Inventory Management, Cold Chain, and Mapping.
A report we have developed to help district or provincial management can show aggregated district performance data on a map based on the location of the health districts. For example, let me show you our mapping report for coverage rates.
(click "map of coverage rates by date range" report, Target: fully vaccinated children Date range: 2009)
Here we have the Coverage Rate Mapping for Fully Vaccinated Children for 2009. Using this unique view of the data, a district or provincial manager can quickly survey coverage rates and identify areas with low coverage.
And that is a quick look at vrMIS3. Thanks!
LONG DEMO SCRIPT (~10 minutes):
I'm going to show you the key vrMIS functionality in this quick demo.
Offline mode
We'll start by accessing vrMIS3 offline landing page which asks for an access code. Currently, the field coordinator, cold chain manager, and administrator all have different access codes. Also note the top right hand corner of the screen where the user can select the language.
Right now, I will show you the field coordinator's tasks with vrMIS3 offline.
(Enter the access code, "fc")
This brings me to the Main Page. All system tasks stem from the delivery zone and visit month, so that is the first thing I need to do as a field coordinator. I am going to select "Centro-Nampula" because I am the field coordinator responsible for the central delivery zone in the Nampula province. Then, I'll select May 2010 as the visit month.
On the right side of the screen is an outline of my monthly tasks as a field coordinator. Notice that this is just plain text.
(Select "Centro-Nampula" and May 2010)
As soon as I select a delivery zone and visit month, some of those monthly tasks turn into links which indicate that these tasks have action with vrMIS3. These 5 tasks are:
Determine how much to take Record warehouse pickup amounts Input the monthly data forms Review the results Upload data.
DETERMINE HOW MUCH TO TAKE (Click on Determine how much to take) This task informs the field coordinator the amounts of medical supplies to pickup for delivery.
Notice that there are two global links: "Log out" and "Go to main page". To return back to the main page and engage in another task, click "Go to main page".
(Click "Go to main page")
RECORD WAREHOUSE PICKUP AMOUNTS (click on Record warehouse pickup amounts)
This data entry task requires the field coordinator to enter the amounts of medical supplies that were ACTUALLY picked up from the warehouse and the date of this warehouse pickup.
(Click "Go to main page")
INPUT MONTHLY DATA FORMS (Click on Input the monthly data forms)
I am now on the "Choose a health center" page. Remember that the field coordinator has already selected their delivery zone. So the districts and health centers listed here are scoped to the delivery zone for easy searching.
This page not only allows the field coordinator to select the health center, but also helps the field coordinator manage the data entry process. Each health center has a data entry status icon which is RED if the record hasn't been started, YELLOW if the record is incomplete, or GREEN if the record is complete.
In front of me, I have a data collection form for the health center Corrane in the Meconta District, so I will use the search bar and locate "Corrane" in order to start entering data.
(Start typing in Corrane in search bar, but then click on the link in the list.)
I am now on the first screen of the data entry process. There are 12 screens which you can see on the left side of the screen that match the 12 sections of the monthly data collection form. Similar to the data entry status icons for the health center on the previous page, each screen has data entry status icon next to it. This helps the user know where missing required information is located.
This first screen asks about the Visit information such as: was this health center visited?. This health center was not visited because rains had washed out the road. So, I click "No, no one visited".
(Click No, no one visited)
Notice that the visit date and vehicle ID field disappeared, and the question "Why did no one visit?" appeared. vrMIS3 has built-in form logic in order to ease and streamline the data entry experience for the field coordinator. I will select "Road impassable or bad weather" to finish the data entry for this screen.
I click the "Next>>" link at the bottom right which will advance me to the next data entry screen.
The field coordinator will work his/her way through the data entry screens in this way.
After completing the data entry process for Corrane, I can click "Change health center" to continue entering data for another health center or click "Go to Main Page" to change tasks.
I am going to engage another task, so I am going to return to the main page.
(Click "Go to main page")
Next, I want to upload the data that I just entered because I now have access to an internet connection. It's important to note that field coordinators can only upload health center records when they are complete. I can't upload incomplete health center data records. So, I click "Upload data".
UPLOAD DATA (Click "Upload data")
An upload window will appear which prompts the field coordinator to enter his/her name and password and click "log in".
(enter "centro-nampula" for username and "demo" for password....click "log in")
After logging in, I can upload completed health center records to the server, so a broader audience can see and use this monthly data.
Online Mode
We'll start with logging into the site mis3.villagereach.org as the field coordinator, with the name of Mr. Centro-nampula. This user is responsible for the zone called “Central Nampula”, which corresponds to a delivery route and consists of a few dozen health centers.
(Login)
Note that once I login, it shows me the application in my native language, but I can toggle over to portuguese. Translating this to French would be fairly trivial and would take less than a week to complete.
The landing page, “to-do” page or dashboard consists of the things that I, as the field coordinator, would be responsible for in the workflow. By default, this page reflects my most important task which is to enter health center data from the field.
The vrMIS system covers the cold chain, logistics management information, and health center data. I'll show you how the field coordinator enters all of that monthly data and how the system keeps track of how much of the data has been entered. That's the meaning of the red/yellow/green icons shown here on the dashboard.
Reports
An important component of managing the information is to being able to visualize and share it. We've leveraged google maps and other open source tools.
(click on View Reports)
There are currently 6 categories of reports: Inventory Management, Cold Chain, Field Coordinator Efficiency, Delivery Intervals, EPI Vaccination Report, Mapping, and Auto-Evaluation.
Let’s say that as a field coordinator, I want to see a report on what percentage of the health centers are experiencing vaccine stock outs. To access this report, I click “% of health centers experiencing a stock out, by date” link under the Inventory Management Report category. Then, I select 2009 a and update the graphs.
In addition to these web-based graphs, I can export the information displayed to CSV by clicking the “Export as CSV” link located at the bottom of each graph. These files can then be sent via flash drive to another computer not connected to the Internet.
I am also able to show the data on a map based on the location of the health districts.
(back to reports via breadcrumb)
Here we have the Stockout Graph Report
(reports, Stockouts by date)
For Polio in the Nampula district for 2009
Cold chain manager
Another role in vrMIS is the provincial cold chain manager. The provincial cold chain manager can login and see the current status of the cold chain.
To navigate back to the login page, I click “Log out” near the top right of the screen. I enter in “manager” as the username and “demo” as the password.
The tasks available to the Cold Chain Manager include: manage the cold chain, manage health center information, monitor field coordinator data entry progress, and analyze reports.
As a provincial cold chain manager, I can use the dashboard feature as a quick check up on the overall cold chain status and also data entry status of the field coordinators. After logging in, I am again presented with a task dashboard. The left side of this dashboard shows the data entry progress of the monthly data collections forms filled out by the field coordinators. The first chart shows the data entry progress in terms of the field coordinators. The second chart shows the data entry progress in terms of the health centers.
Using these charts, the manager gets a quick look at how far along the field coordinators are with their monthly data entry.
On the right side of this dashboard, I am presented with several charts around the status of the cold chain. Chart 1 shows the current percent breakdown of each status category (Green, Yellow, and Red). Green represents working refrigerators, yellow represents refrigerators with problems, and red represents broken refrigerators. I can use this graph to immediately assess the health of the cold chain. If I wanted a list of refrigerators currently experiencing a problem (Yellow), I click the linked number next to Yellow which represents the refrigerator total of this status.
The content below can provide the manager with a more in-depth understanding of the health of the cold-chain.
Cold Chain Task
On the left, the current non-working refrigerator statuses are broken down by severity with “Broken” refrigerators at the top then followed by missing refrigerators and refrigerators currently experiencing a problem.
And that's a short demo of VRMIS. Thanks!
END OF DEMO###