Facility Data Module

Owned by Mike Seaton
Last updated: Dec 17, 2017 by Fawwaz YusranVersion comment
12 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.