Address Hierarchy Advanced Features

Owned by Mark Goodrich
Last updated: May 09, 2019 by Brandon IstenesVersion comment
4 min read

Overview | Advanced Features | Release Notes

Address To Entry Mapping

It is important to note that the module does not provide direct mappings between a Person Address and an Address Hierarchy Entry.  For example, if the "City" field in a Person Address is set to "Boston" via the address hierarchy, the string "Boston" is simply stored in the "City" field; no keyed relationship is created between the entry in the Person Address table and the "Boston" entry in the Address Hierarchy Entry table.  

The Address Hierarchy module provides a utility that can be scheduled to compare Person Addresses to Address Hierarchy Entries at regular intervals, and store keyed relationships between addresses and entries in a separate address_to_entry_map table.  This table is NOT currently used by module itself, but can be used as a reference for writing custom reports, etc. This functionality is turned off by default, but can be configured via the Advanced Features page in the administration section.  

To configure this functionality, check the "Check for address changes and update associated mappings..." check box on Advanced Features page, and specify the repeat interval for this task.  The first time the this task is run, it will scan all the non-voided Person Addresses in the system and create Address To Entry Mappings for any matches it can find between addresses and entries.  The next time the task is run, it will recalculate mappings for any addresses that have been updated since the previous run.

Interaction with Sync module

Note that an Address To Entry Map is a standard OpenMRS object, so it will be synchronized by the Sync module unless explicitly excluded.  Therefore, the Address To Entry mapping utility need only be configured on a single server when used within a mult-server environment.

User-Generated IDs

As of version 2.2.6, the module supports specifying "user-generated ids" for each address hierarchy entry when importing a hierarchy.  A "user-generated id" is simply a free-text property of an address hierarchy entry that allows implementaters to store in the database some custom information for each entry.  Currently, the module doesn't support any functionality for the ids beyond importing them, so at this point they really can only be accessed via sql queries, or custom-written code.

A user-generated id is appended to the end of an entry name, separated by a specified delimiter.  For instance, here is an example of a standard pipe-delimited import file with user ids delimited by the percentage character (%): In the example below, the Delimiter would be "|" and the User Generated ID Delimiter would be "%". Neither delimiter includes the double quotes. 

United States%001|Massachusetts%002|Suffolk County%004|Boston%007
United States|Massachusetts|Plymouth County%005|Scituate%008
United States|Massachusetts|Plymouth County|Hingham%009
United States|Maine%003|Cumberland County%006|Portland%010

Note that for upper-level entries that appear more than once within the import file (United States, Massachusetts, Plymouth County) the user-generated id only needs to be specified one, though it is not problematic if it is specified more than once. In the event that more than one id is specified for a single entry, the id that ends up being stored is arbitrary (i.e., in a proper import file, no entry should have more than one id!).

Developer Tools

Upon start-up, the address hierarchy module loads it's entire address cache into memory to speed up address searches.  Since this slows down module startup, as of version 2.2.6, developers may wish to turn this functionality off during development, This can be done by setting the global property addresshierarchy.initializeAddressHierarchyCacheOnStartup to false.

Activator Loading of Address Configuration & Entries 

As of version 2.11.0 it is possible to let the module activator load the address configuration and address hierarchy entries upon starting. The activator will scan the following location in the app data directory:

App data dir
.
|_ configuration/
   |_ addresshierarchy/

Two files are excepted to be found in there:

addressConfiguration.xml

This file defines both the address template and the address hierarchy entry levels in the hierarchy. Furthermore it indicates the location of the second configuration file. Here is a sample file:

addressConfiguration.xml
<addressConfiguration>
  <wipe>true</wipe>
  <addressComponents>
    <addressComponent>
      <field>COUNTRY</field>
      <nameMapping>Location.country</nameMapping>
      <sizeMapping>40</sizeMapping>
      <elementDefault>Cambodia</elementDefault>
      <requiredInHierarchy>true</requiredInHierarchy>
    </addressComponent>
    <addressComponent>
      <field>STATE_PROVINCE</field>
      <nameMapping>Location.province</nameMapping>
      <sizeMapping>40</sizeMapping>
      <requiredInHierarchy>true</requiredInHierarchy>
    </addressComponent>
    <addressComponent>
      <field>COUNTY_DISTRICT</field>
      <nameMapping>Location.district</nameMapping>
      <sizeMapping>40</sizeMapping>
      <requiredInHierarchy>true</requiredInHierarchy>
    </addressComponent>
    <addressComponent>
      <field>ADDRESS_1</field>
      <nameMapping>Commune</nameMapping>
      <sizeMapping>40</sizeMapping>
      <requiredInHierarchy>true</requiredInHierarchy>
    </addressComponent>
    <addressComponent>
      <field>CITY_VILLAGE</field>
      <nameMapping>Location.village</nameMapping>
      <sizeMapping>40</sizeMapping>
      <requiredInHierarchy>true</requiredInHierarchy>
    </addressComponent>
  </addressComponents>
  <lineByLineFormat>
    <string>cityVillage, address1</string>
    <string>countyDistrict, stateProvince</string>
    <string>country</string>
  </lineByLineFormat>
  <addressHierarchyFile>
    <filename>addresshierarchy.csv</filename>
    <entryDelimiter>,</entryDelimiter>
    <identifierDelimiter>%</identifierDelimiter>
  </addressHierarchyFile>
</addressConfiguration>

When wipe is set true the existing address hierarchy entries will be wiped before loading the address hierarchy entries from the CSV import file. On the other hand setting wipe to false allows to add additional entries to a persisted set already in database.

Note that entryDelimiter and identifierDelimiter are interpreted as Regex. As a result, delimiters which are special characters in Regex must be backslash-escaped. If you want to specify an address hierarchy with lines like

  UK^001|London^10001|Steve's House

Where 001 is the identifier for the UK, then your configuration should read

  <entryDelimiter>\|</entryDelimiter>
  <identifierDelimiter>|^</identifierDelimiter>

The CSV import file for address entries

Based on the above sample configuration this file is expected to be named addresshierarchy.csv.
This is the usual address hierarchies CSV import file, see 'Importing an Address Hierarchy' for more details about it.