Facility Data Module

Owned by Mike Seaton
Last updated: Dec 17, 2017 by Fawwaz YusranVersion comment
13 min read

Overview

A standard OpenMRS implementation focuses on collecting data within and about a patient - encounters, observations, orders, etc.  However, at many health facilities, only a fraction of the overall patients are actually captured in OpenMRS.  Some implementations may only manage HIV patients, or only TB patients, or only collect limited patient registration data. Although other patients are still being seen and cared for at the health facility, the data surrounding their care is not captured within OpenMRS.  Reporting requirements - to funding agencies, for monitoring and evaluation, etc - may be such that some of a given report's data is captured in OpenMRS patient records and some of it is not.  This leaves a gap in what is achievable with standard OpenMRS tools to fully produce such reports.

Additionally, there are many important pieces of data within a health facility that are not patient-centric at all. These include questions such as "Are critical supplies in stock?", "Are services like internet, power, and lab equipment functioning correctly?", "How many community health worker training sessions were held last month?"  etc.  Although not patient-centric, these data points may still be important for monitoring and evaluation and ensuring quality care at a particular health facility.

The facility data module is meant to address these gaps. It's goal is to provide a mechanism for defining facility-level data collection forms, which are filled out on a regular, periodic basis, and which can capture the data points which are important to your organization.

Installation and Configuration

  • Download from the module repository

  • Grant any required privileges

    • View Facility Data Reports: Allows users to view and analyze entered data

    • Enter Facility Data Reports: Allows users to enter facility data

    • Manage Facility Data Reports: Allows users to create, edit, delete forms, questions, and question types

  • Configure global properties

    • facilitydata.unsupportedFacilities: An optional comma-separated list of location ids. If supplied, this will hide those locations from within the user-interface. Otherwise, will show all

    • facilitydata.dailyReportDaysOfWeek: An optional comma-separated list of days of the week. If supplied, this will enable entry for DAILY reports only on the days specified. (Sunday = 1, Monday = 2, ... Saturday = 7). To support entry for weekdays only, you would enter 2,3,4,5,6

  • Navigate to the facility data dashboard, accessible from the Administration page

Administration

Using the facility data module is a fairly simple process. Your first step is to figure out what data you wish to collect and how often you wish to collect it. Currently the facility data module supports forms that are entered daily (either every day or a subset of days per week, per the global property above) or monthly. Each form can contain one or more sections to logically group questions together. Questions are defined independently of forms, and the same question can be added to multiple forms. Each form can customize the display label and question number that is associated with a particular question that has been added to it. Each question that you create must be associated with a particular user-defined question type. Question types fall into 2 broad categories - numeric or coded, and fully control the allowable answers for a given question. Users should define as many instances of numeric and coded question types as they need to meet their specific data collection requirements.

Administering Question Types

As described above, question types are the means for specifying the allowable answers for a given question. Because of this, defining these will likely be done at the same time that you defining your first questions. However, ongoing these are likely to be rather stable and will be continually re-used among new questions that you define. Because you must specify a valid question type when you create a new question, creating your question types come first. Here are some examples of how question types are envisioned in use:

  • Positive Integer (Min Value = 0, Allow Decimals = False) - for questions like "# of pediatric vaccinations administered today"

  • Number of Days In Month (Min Value = 0, Max Value = 31, Allow Decimals = False) - for questions like "# of days without internet this month?")

  • Boolean (options: True, False, Unknown)

  • Stock Status (options: In Stock, Critically Low, Stocked Out, Not Applicable)

Steps for creating or editing a question type:

Screenshots

Steps for creating or editing a question type:

Screenshots

  1. From the facility data dashboard, click "Manage Question Types"

  2. To edit an existing Question Type, click the name of the Question Type from the displayed list

  3. To add a new Coded Question Type, select "Coded" from the list, and click "Add"

    • Name: A descriptive name for this type (eg. Boolean)

    • Description: An optional way to further describe what this represents

    • Coded Options: The allowable values for this Question Type. For each coded option, you can specify:

      • Name: The name of the answer (eg. True). This will be the value that is displayed in the form

      • Code: A label-agnostic code for the answer, that might be used in analysis applications to equate two otherwise different options

      • Description: A description that further clarifies what this option represents

  4. To add a new Numeric Question Type, select "Numeric" from the list, and click "Add"

    • Name: A descriptive name for this type (eg. Positive Integer)

    • Description: An optional way to further describe what this represents

    • Min Value: The minimum allowed value for this type (optional)

    • Max Value: The maximum allowed value for this type (optional)

    • Allow Decimal Values: If unchecked, only whole numbers are allowed

Administering Questions

Once your question types are defined, creating questions is very simple.

Steps for creating or editing a question:

Screenshots

Steps for creating or editing a question:

Screenshots

  1. From the facility data dashboard, click "Manage Questions"

  2. To edit an existing Question, click the name of the Question from the displayed list

  3. Any existing questions that are not in use will have a trashcan icon to their right in the list, which will allow you to delete those questions

  4. To add a new Question, click the "Add New Question" link

    • Name: The name of the question. This will be the default value that is displayed in the form, if not overridden at the form level.

    • Period Applicability: Additional metadata that describes the context of this question with respect to the entry period for which it is answered. For example, a question like "# of patients on treatment at the end of the month" will have a Period Applicability of AT_END_OF_PERIOD, while a question like "# of vaccinations performed this month" will ave a Period Applicability of DURING_PERIOD

    • Question Type: The question type, as defined per the above instructions

    • Description: An optional way to further describe what this question represents

Administering Forms

Once you have your questions defined, you can put these together into forms, within one or more sections. To be more precise, once your questions are defined, you can put these together into one or more form schemas, within one or more sections. A schema is the actual part of the form that contains the questions, and a particular form may have one ore more schemas associated with it. The reason why this is done is to support versioning. It is common, particularly for forms which are filled out in order to report a particular set of values to a funder or Ministry of Health, for the questions on these forms to change constantly. By abstracting out the questions that are asked for a given time frame from the conceptual form that is being completed, we can support this more easily.

For example, let's say we want to create a form for capturing daily vaccination metrics to report to the ministry of health. We have defined our question types and questions, and now it is time to build the form. We can do this by completing the following steps:

Step 1: Create a new form

Screenshots

Step 1: Create a new form

Screenshots

  1. From the facility data dashboard, click "Manage Forms"

  2. Click the "Add a New Form" link

  3. Give this form a name (eg. Daily Vaccination Report)

  4. Select a frequency for how often this form is completed (currently Daily and Monthly are supported)

  5. Initially, the schema name can be left blank, and it will default to the name of the form you are creating. You can fill this in if you want, but it doesn't typically make sense to give a form and a schema different names, if the form has only one schema associated with it.

  6. The schema "valid from" date should be set to the first day that you plan to roll out the completion of these forms. Doing this will ensure that analysis utilities are correctly able to report on forms that are missing or incomplete.  The "valid to" field should be left empty until use of this form has ceased - either because it is no longer needed or because a new version has been rolled out (more on this below).

  7. Click "Save form schema", and this will take you to a summary view for the form's schema

 

Step 2: Add one or more sections to the form

Screenshots

Step 2: Add one or more sections to the form

Screenshots

Let's say we want to add 2 sections to this form: "Vaccinations administered", and "Vaccination stock status". We can do this by clicking on the "Add new form section" link on the schema summary page, and providing the appropriate name when prompted - once for each section. Once these have been created, you will notice that each section has the following actions available:

  1. Edit - this takes you back into the dialog where you first created the section, and allows you to change the name

  2. Move Up - if the section is not the first listed, this allows you to move it up in order

  3. Move Down - if the section is not the last listed, this allows you to move it down in order

  4. Delete - this allows you to delete the given section. If the section contains questions, you will be prompted to specify a valid section to move these questions into, since all questions must exist within a section

 

Step 3: Add one or more questions to each section

Screenshots

Step 3: Add one or more questions to each section

Screenshots

To add questions to a particular section, you first need to select the section you wish to work with from the select list on the right of the schema overview page. Once you have done that, clicking "Add a new question to this section" will give you a dialog box with 3 fields:

  1. Question Number (eg. 1.A.)

  2. Question (pick the question from the list that you want to ask, as defined in the "Administering Questions" section

  3. Display Name for this form: When you pick a question from the list, this will auto-populate with the name of the question. However, you can change this here to whatever text you want displayed on the form. This allows you to have the same question added to multiple forms, but displayed slightly differently on each, as well as to keep your internal question names independent of a particular display label that might change over time.
    Clicking "Save" will add this question to your section.
    Once a question has been added, you will notice that the following actions are available:* Edit - this takes you back into the dialog where you first created the question, and allows you to change the details* Move - this allows you to move the question into a different section* Delete - this allows you to delete the given question. This option is only available if no values have been entered for this question.
    You will see from the screenshots to the right, that we have added 2 sections - the first with two questions, and the second with one question.

At this point, your form is ready to use, and you can skip down to the next section on Entering and Viewing Data. However, to continue the documentation on Administering forms, we will continue here with further steps for how to adjust to changing form requirements over time...

Step 4: Make a new version of an existing form

Screenshots

Step 4: Make a new version of an existing form

Screenshots

It is very common for data collection forms such as these to change over time - questions are added, questions are removed, questions are changed slightly, etc. To handle this in a way that preserves existing form data faithfully, we can create new form schemas that are associated with an existing form, and set validity periods on each schema to record which questions were in use at which point in time. To carry on with the above example, let's say that we wanted to add some additional vaccination stock status questions that we were not previously tracking:

  1. On the schema summary page for our current form, we first want to enter the "valid to" date that this schema will stop being used. We can do this by editing the schema, by clicking the "Schema details" link above the name of the schema, setting the field, and saving.

  2. At this stage we may also want to edit the name of the existing schema in such a way that identifies it as being different from the new schema (see screenshot).

  3. Once we have made this change, we can create a new version of the schema by clicking the button on the bottom of the schema summary page labelled "Create a new version of this form". You want to fill in the date that this change takes effect (see screenshot) and hit submit - this will create a new schema, with exactly the same sections and questions as the original schema, but with a "valid from" date that is set to the date you indicated.

  4. You can confirm that this is a new schema by returning to the Manage Forms page (see screenshot), where you will see 2 different schemas listed for your form.

  5. Returning to your new version of the form, you can add your additional questions in (see screenshot)
    We will see the how this impacts the data entry process in the next section...

Entering and viewing data

Once forms are created, users can start entering data. To facilitate this, a dashboard is presented for each form that displays the data entry status of a range of dates, by facility. This provides a useful summary of what data entry forms are not yet entered, entered incompletely, or completed, as well as what dates are not applicable for entry, due to schema validity periods or global property configuration. See the screenshots below for examples of what this looks like for new forms which are entered Daily and Monthly.

From this dashboard view, users can click "Enter" on a particular cell to fill out a form for the selected period and location. Each form provides an appropriate input for each type of question that is defined, as well as a field for recording any comments, as needed. Once saved, a report displays in view mode, with a button to further edit it if desired. When you return to the dashboard, if a report is partially completed, it will show up as yellow. If a report is fully completed, it will show up as green.

Data management tools

For the initial release of the module, this section contains a single tool, available by clicking "Data completion and aggregate analysis". This tool allows you to choose a Schema, optionally limited by Facility and date range, and to generate a summary report that provides the aggregate answers to each question in the schema for the criteria specified, as well as an indication of how many reports were completed.

Data export and analysis tool

For the initial release of the module, this section contains a single tool, available by clicking "Export raw values to Excel". This tool allows you to choose either a form or a question, optionally limited by Facility, date range, and entered date range, and to export all entered values to Excel that match this criteria. This exported spreadsheet contains 2 sheets - one with the exported data, and one that contains the details of the export query. See screenshots below and to the right

Release Notes

  • 2.0: Initial release (NOTE: THIS IS NOT BACKWARDS COMPATIBLE WITH THE 1.0 RELEASE)

  • 1.0: Initial alpha release

Contacts

Project Lead:

@Mike Seaton

Contributers:

@Dupuy Rony Charles

 

Robert O'Connor (Google Summer of Code 2009)