Address Hierarchy Module

Overview | Advanced Features | Release Notes

Overview

In the standard OpenMRS implementation, all the address fields for patient addresses are free-form text boxes. The Address Hierarchy module provides the means to override this standard functionality with drop-down lists populated from an imported address hierarchy.  Users can then specify the address for a patient by selecting the appropriate locations from the hierarchy.

Open

1) User selects the district "Berea" from drop-down list

Open

2) Community Council drop-down updates to show all councils within Berea district.

3) After a council is selected, village drop-down updates to show valid villages in selected council area.

Requirements

Starting with version 2.2.5, the module requires OpenMRS 1.7.x or higher.  Previous 2.x versions of the module are compatible with OpenMRS 1.6.x.

Download

The latest version of the module can be found in the OpenMRS Module Repository.

Usage

Once you have the Address Hierarchy module installed on your system, you must import an address hierarchy and configure it before it will function properly.

Importing an Address Hierarchy

An address hierarchy is imported by uploading a standard text file that contains the locations in the hierarchy. Each line in the hierarchy defines a full "path" in the hierarchy, from the top level location to the bottom-most location.  For example, here is a sample file defining a few locations within the United States:

Note that there are no limitations to the characters within a location name with the exception of the double-quote (") character (and, of course, whatever delimiter you chose).

To upload an address hierarchy, go to the Administration page and select Manage Address Hierarchy from the Address Hierarchy Module section. An Upload Address Hierarchy box allows you choose a file to upload, specify the delimiter, and select whether or not to overwrite any existing address hierarchy entries.  Any character (or set of characters) can be used as a delimiter, but the delimiter field expects a regular expression, so if your delimiter is a special regex character (like the "pipe" character in the example above), keep in mind you must escape it using a backslash.  For the example above, the regular expression would be "\|", not including the double quotes.

Note that as of version 2.2.6 also provides for the import of user-generated ids.  This is an advanced feature and more info can be found here.

Configuring Address Hierarchy Levels

Once you've uploaded an address hierarchy, you must map the levels in the hierarchy to the appropriate address fields. The Manage Address Hierarchy page provides an overview of the levels in your hierarchy, along with a sample entry and the number of entries at each level.  

Click on "Edit" to map an address field to a specific level.

The address field levels available are driven by the address name mappings configured for the active address layout. (Prior to OpenMRS 1.9, address layouts are defined in openmrs-servlet.xml, but starting with release 1.9, you can set up custom address layouts without modifying openmrs-servlet.xml).

A hierarchy level does not necessarily need to be mapped to an address fields, but only mapped levels will appear when editing an address.  For instance, in the example above there are six hierarchy levels, but only three are mapped to address fields--and, therefore, it is only these three fields that appear when selecting an address.  (The module is intelligent enough to calculate valid possible address values while skipping levels in the hierarchy.)

You can also set a name for a hierarchy level, but, currently, this is only for reference and is not used outside of the administration section.  

Finally, you can set whether a level is required or not.  If a level is required, an update to an address will be disallowed if the address field associated with that level is left blank. All levels default to not being required. 

Free-text Address Entry

Users are allowed to enter free-text for addresses by selecting the Other option from the drop-down list:

If you do not wish to allow free-text entry, you can disable it by setting the global property addresshierarchy.allowFreetext to false.  When this property is set to false, Other will not appear as an option in the drop-down list.  If there are patients with existing free-text entries that don't match the hierarchy in the system, these free-text addresses will still be displayed, but users will not be able to update an address without switching all fields to valid hierarchical entries.

It is also possible to configure the module so that some of the address fields are driven by the hierarchy and others are free-text.  This commonly occurs at lower levels of the hierarchy.  For example, you may want City and State to be driven by the hierarchy, but allow free-form entry for Street.  In this case, from the Manage Address Hierarchy page you can add one or more levels to the bottom of the hierarchy. Here we have added a level associated with the Address field to the hierarchy:

Note that the Address level has no entries.  Any hierarchy levels without any corresponding entries in the hierarchy will be rendered for editing with free-text fields:

Reference Application Registration App Integration

It is possible to use the Address Hierarchy with the Reference Application Registration App.  You simply need to tell it to use the Address Hierarchy widget rather than the standard text-box widget. For complete instructions on how to do this, see the Registration App Configuration.

Previous Versions

Significant functional and data model changes were made in the jump from version 1.2 of the module to 2.0.  Documentation for the old version of the module can be found here:

• Address hierarchy user guide (Prior version)

• Address hierarchy technical overview (Prior version)

Upgrading from 1.x

Upgrading from an earlier version to version 2.0 of the module should be a painless experience.  However, to date, this has not be fully tested--it is recommended that you test the update first on a non-production server.  Upon installing the module, any existing address hierarchy should automatically migrated to the new data model.  Then you will need to map your hierarchy levels to address fields before the new module will function properly.  The first thing you should do is go to Manage Address Hierarchy and set up your mappings as described in the Configuring Address Hierarchy Levels section.

One significant difference between 1.x and 2.0 is that 2.0 provides no means to directly edit your address hierarchy entries--all location data is imported via uploading files.  If you don't have your locations stored outside of OpenMRS in a format that is easily exported to a delimited text file, you may want to hold off on upgrading. 

Bugs, Questions, & Feature Requests

Please report any bugs by opening a ticket at http://tickets.openmrs.org.  Don't forget to set the project to the Address Hierarchy module.

For questions or feature requests, please post to either the OpenMRS developers or implementers list.