Household Module

Table of Contents


Patient programs need the ability to record and retrieve household-level information.  Since OpenMRS is a patient-centered medical record system, it is not an ideal target for storing or managing household-level data.  An enterprise-quality household information system would likely run separately and integrate with OpenMRS and other applications; however, an adequate place to start with household data is through an OpenMRS module that is loosely bound to OpenMRS – i.e., taking advantage of the users & authentication provided by OpenMRS without building so many dependencies that it cannot be extracted into an external system in the future


What the module will do:

  • Support multiple – possibly overlapping – definitions of households.
  • Allow households to be created and identified by a unique household identifier.
  • Support the addition of person(s) to a household
  • Allow persons to have 0-to-n identifiers as well as supporting a [UUID] for each person.
  • Provide CRUD (create, read, update, and delete/void) operations for household-level encounters & observations.
  • Allow for persons to be in multiple concurrent households.
  • Allow for persons to leave and return to households any number of times – i.e., support a time frame for "household memberships".
  • Provide an API, including a web-based API, for adding, retrieving, and managing household data.

What the module will not do:

  • This module will not support business logic that is not directly related to defining & recording data for households – e..g, a system that wants to track food delivery to households. They can use this module to manage household definitions and record household-level data, but will need to perform supply chain management & enforce limits on amounts dispensed itself.
  • This module must not become tightly bound to OpenMRS, since it will be more generally useful if it – at least the core functionality – can be used within other contexts.
Step by step module usage

  • Install the module through the [Admin -- > Manage Modules] NB: If u had previously installed Household module version 0.1 you may need to change to settings (formerly Global Properties from paltform 1.8 downwards) for the database version to 0.0.0 before uploading this module
  • Select "Household Settings" link and specify the site on the settings (formerly Global Properties from paltform 1.8 downwards) [household.siteacronym] e.g. Nairobi will be "NBI". This will help you distinquish site of household registration
  • On the Household module, select the Definitions/Groups and enter the code e.g. PHC, Primary Health Care, The index here will be ....
  • You can begin doing registration of individuals to a household on the "Registration" link.
    • On the textbox "Find Household Member" type the first 3 initials of the person name u want pulled or more.
    • Select the person(s) you want included. 
    • Choose the Definition which you had earlier registered
    • Select the start date the household was captured
    • On the list that will have populated, choose the index/head of the household.
    • Click save to register the household
  • Upload site locations that u want to use e.g. District, Division, Location, Sublocation
    • Use a CSV format file to upload locations comma separated.
    • Since this capitalizes on the Address Hierarchy module, you can customize the same by studying the Address hierarchy module on how to specify locations.
  • You can then capture the encounter types to be used by definitions  by capturing at the  "Encounters" link. e.g. PHC Initial Encounter.
    • NB: CHW Initial Encounter is provided to help with the people who wan to see how the household module can be used as HTML Form Entry is being customized to allow for Household Observations
    • For individuals who have been registered into a household, the household tab on the patient dashboard will show the members of that household and the encounters that have been already captured to that household.

  Please follow this link.

Release Notes

Ongoing Development

Example usage


Source code:           source in github

Openmrs Module:    omod file

Tickets link:            HSHOLD project in JIRA


Data model

Original documentation

Project Documents