How to use the Address Hierarchy Module with the Reference Application

I am implementing OpenMRS at St. Luke’s hospital in Port-au-Prince, Haiti. We need to use the Address Hierarchy Module, and we want to use the Reference Application (and it’s registration App). The work has been done to enable these two to function together. See…

How can I use the Address Hierarchy Module with the Reference Application without writing a custom module to map the fields? Or perhaps PIH or @mogoodrich or @darius or @ball has a module that would work with PIH’s great Haiti Hierarchy which we are using.

Any help would be greatly appreciated.

1 Like

@arbaughj yes, it’s definitely a shame this isn’t documented better… have been searching through the code for some good examples.

First off, to customize registration you will probably need to fork your own version of the reference app module, and then custom the *json files within it.

Stealing from another thread, the Ebola reference app has the best example of how to set up a json file to configure the registration app. This probably has more than you need, but is hopefully a start!

This example does not include using the address hierarchy module, but switching it out to use the address hierarchy should be straightforward (fingers crossed!)…

The main step would be to replace, in the personAddress section, the configuration of the address widget from:

"widget": {
                 "providerName": "uicommons",
                  "fragmentId": "field/personAddress"


 "widget": {
           "providerName": "registrationapp",
           "fragmentId": "field/personAddressWithHierarchy"

This should give you an out-of-box widget based on the hierarchy you have configured via the address hierachy module. Furthermore, if necessary, you should be able to config the widget as follows:

"widget": {
     "providerName": "registrationapp",
     "fragmentId": "field/personAddressWithHierarchy",
    "config" : {
        "shortcutFor": "address1",
        "manualFields": ["address2"]

Where “shortcutFor” will render a autocomplete search on that field that appears above the hierarchical selection (for example, in Haiti, we use this config to provider a shortcut search on “Locality” that users can use to find a specific locality without having to navigate through the whole hierarchy), and “manualFields” is the set of fields that allow manual (ie non-hierarchical coded) entries.

Hope this gives you a start! Let me know if you have further questions…


You do not actually need to fork the reference application module for this. You can use System Administration -> Manage Apps -> Add App Definition for this.

But as I’m sure you know, you do need to put a big block of json configuration in that textarea, so it’s not really easier than doing this as code. :smile:

Hi @arbaughj have you successfully used the "manualFields" of the "field/personAddressWithHierarchy" widget? I am stuck on this one and wondering what I am missing…

Perhaps could you have a look at this other thread written specifically about this issue?

Any help or directions would be so appreciated. Cheers.

Dear @mksd, you are ahead of me. I haven’t had time to try it out yet, but I’m not really a dev. I hope you can figure it out, because I suspect I will need your help.

@darius and @mogoodrich, thanks for your help with this. I had problems with the Ebola example file when I attempted to save the App Definition. I found this file and copy and pasted (without the square brackets), and it saves properly…

After saving the new App Definition, I stopped the legacy one. I made minor changes to my new json code, like changing the App ID and name, and the changes take effect.

When I try to replace…

"widget": {
                 "providerName": "uicommons",
                  "fragmentId": "field/personAddress"


"widget": {
     "providerName": "registrationapp",
     "fragmentId": "field/personAddressWithHierarchy",
    "config" : {
        "shortcutFor": "address1",
        "manualFields": ["address2"]

it doesn’t make any changes in the Registration App UI.

I tried the legacy UI, and I see the Address Hierarchy field names, but no drop-downs or blank fields. So, something is probably not properly configured with the Address Hierarchy Module. I’m using Address Hierarchy 2.7 on OpenMRS Version: 1.11.4 Build 6ebcaf. Are there any known compatibility issues?

Thanks so much for your help.

@arbaughj are there any errors in the javascript console?

@mogoodrich, there is a console error on the 2.x UI…

https://localhost:8080/openmrs/ms/uiframework/resource/uicommons/styles/styleguide/images/ui-bg_flat_75_ffffff_40x100.png Failed to load resource: the server responded with a status of 404 (Not Found)

On the legacy UI, it gives a helpful error…

Uncaught Error: Syntax error, unrecognized expression: []

Any idea where I should look to fix this?

@mogoodrich , I tried Stopping the Address Hierarchy Module, and it doesn’t give the JavaScript console error I mentioned previously, so the error is related to Address Hierarchy Module.

I also, if the address Hierarchy Level is not mapped to an Address Field, there are no errors shown.

The error is always shown for the first mapped address field. For example, if I map Address 1, the console error is…

Uncaught Error: Syntax error, unrecognized expression: [name=personAddress.address1]

There aren’t errors related to the fields below the first mapped one.

The address hierarchy seems to work alright when setting an address for a location. Perhaps the console error on the legacy patient dashboard is a red herring.

Good morning @mogoodrich. I troubleshooted the Address Hierarchy Module most of the morning.

I looked at the database fields, and noticed the User-Generated Id’s were on the name, and not in the appropriate column. I cleared out the configuration and re-imported the addresses, and got it imported properly. The above errors still persist.

I tried installing/configuring the Address Hierarchy Module on OpenMRS 1.11.4 Standalone, and found the same JavaScript error when adding a patient.

I found a test server that I could upload a module to…

It is running OpenMRS Version: 1.10.2 SNAPSHOT Build 57bdf2. I configured the module basically the same as my other tests. On this server, the address hierarchy works properly when adding a patient.

I think the latest version of Address Hierarchy Module has a compatibility issue with the latest version of OpenMRS Platform 1.11.4. Is anyone successfully running it on this version?

I tried configuring my custom “App”, by copying the json script over to the test server, but address hierarchy didn’t work in my custom Registration app there either. That server has older versions of the Registration modules, so perhaps they were before address hierarchy was supported. I didn’t want to “break” the server, so I didn’t try updating them.

I’d also like to add some next-of-kin fields (person attributes), like the ebola example. I tried copying in those sections of code, and changing the UUID, but that doesn’t work either. My json configuration is…

I hope you have a nice weekend.

Hi James, I just did this too, so it’s fresh on top of my head :wink:

In fact the UUIDs that you use for all these "type":"personAttribute" fields must be defined beforehands in Administration \ Person \ Manage Person Attribute Types. For instance the phone one (UUID = 14d4f066-15f5-102d-96e4-000c29c2a5d7) is in there out of the box. I didn’t want to have to configure anything through the admin UI so I added the required ones through our module’s Activator.

P.S. Strangely there is a mother’s name available out of the box, UUID = 8d871d18-c2cc-11de-8d13-0010c6dffd0f .

Sorry, been trying to follow this but i have too much going on! We are using OpenMRS 1.10.x, so I can’t attest to address hierarchy with OpenMRS 1.11.x, but I believe the Bahmni install is running 1.11 with address hierarchy.

As for issue… I’ve afraid I don’t I’ll be able to get much farther on it with a test instance I can take a look at. @arbaughj, I got a little confused with exactly what you were able to install on devtest03 and what worked and what didn’t… are you able to get devtest03 in a state that it can reproduce the issue?

Take care, Mark

Good morning @mogoodrich ,

Thanks for your help with this. I know you’re a busy man. My test of configuring the JSON file for the Registration App didn’t work on devtest03. But, I can’t reproduce the problem on the legacy patient dashboard on devtest03, I went through the same process as I did on my other servers, but it worked (address hierarchy is available on the legacy patient creation screen) on devtest03. That’s what makes me think it’s a compatibility issue with OpenMRS 1.11.4, because it works on devtest03 which is OpenMRS 1.10. To confirm this, I downloaded Version: 1.10.2 Standalone and configured Address Hierarchy. The address Hierarchy worked perfect in the legacy UI. I feel almost certain that it’s a compatibility issue with OpenMRS 1.11.4.

@mksd, which platform are you using? OpenMRS 1.10 or OpenMRS 1.11? Thanks so much for sharing your thoughts on adding Person Attributes. It seems like you’re JSON is almost like mine. I just tried to simplify it by just trying the Mother’s name to start. It still doesn’t appear on the Registration App.

For the Reference Application Registration App, it appears my JSON (configured through the UI under Manage Apps) isn’t being used (other than to change the app name). When I remove the JSON code that specifies the address and phone number fields, they still appear in my “custom” Registration App. So, this might be why the address Hierarchy isn’t working in the Registration App. , and why my new sections for Next of Kin aren’t appearing in the app. Could this be the same bug with loading in the JSON that was mentioned here? How to use “manualFields” with a “field/personAddressWithHierarchy” @mksd did you create a ticket for this?

Yep, yes, just testing out the sample you sent me it appears that the Address Hierarchy module integration with the create patient section of the legacy UI is broken in OpenMRS 1.11.x. I don’t know if this would be a priority to fix.

Have we tested if it works within the new patient registration against OpenMRS 1.11.x?


Hi James, no I was still trying to troubleshoot that one myself when I had time. But I guess it would be better now to report the bug. I have a similar issue here too in the context of the Reg. App:

For info I’m using OpenMRS Platform 1.11.4 and I tried all this with the registrationapp 1.3 and 1.4-SNAPSHOT.

Thanks @mksd for the info. So, my problems must be something not related to the versions.

@mogoodrich, Thanks for your continued assistance.

Aha, good news @arbaughj… I figured out your issue… it was easy (but not at all obvious or well documented).

You correctly disabled both of the existing reigstration apps, and then added your own configuration for a registration app, but, note when you configure it to add a button the home page and specify the url you have:

“url”: “registrationapp/”

This is, in essence, still calling the built-in ref app registration app. You need to replace the appId with the appId you specified earlier in the json (registrationapp.registerPatient.wAddHierarchy) so that the registration app module properly picks up your custom configuration.

Take care, Mark

YES! Thank you so much @mogoodrich! It is now showing the things I configured in the json, including Address Hierarchy, and my person attributes!

A few problems…

  1. Address Hierarchy goes down as far as District, showing me a list of available options. I can’t get a list of items for the “Address” field unless I choose the “Yon lot peyi”, “-”, “-”, “-”, “Yon lot”. For example, try “Haiti”, “Ouest”, “Tabarre”, “3ème Bellevue”, and there is nothing in the last box. But, it’s configured and works when adding an address to a location. After further research, it’s because of special characters that are in the address name for example; “1ère L’Arbre”. The same is problematic in the other fields above, if you select a name containing special accented characters, it breaks all of the fields below it. Is there a work-around for this other than taking out the accented characters?

  2. If I type anything in the “Address 2” field, it is erased as soon as I leave the field. It’s like the “manualFields”: [“address2”] isn’t being observed. This is the same problem @mksd had, right? Nothing is logged, and there are no JavaScript errors for items 1 or 2 above. These items are “show-stoppers”. The rest of these would be “nice to have working”.

  3. I don’t see that “shortcutFor”: “address1” in my json does anything. I don’t know exactly what to expect, so I don’t know what I’m missing out on.

  4. There is no “Other” option in the hierarchy, even though “addresshierarchy.allowFreetext” is set to “true”. In the legacy UI, choosing “Other” would give a text box to type in free text for something that wasn’t in the hierarchy.

  5. It doesn’t appear that it respects the required fields per the address hierarchy configuration. Only one field is required, which is the default for Registration App.

  6. Question: Is there an easy way to change the labels for the address fields?

  7. My Person Responsible Relationship is configured against a concept, but it appears as a free-text field. Is there a way to specify a list of options rather than the free text field? Perhaps there is another widget that I could use in the place of “fragmentId”: “field/text”.

  8. When I click to “Show Contact Info”, the address doesn’t show special characters properly. For example it shows… Haiti, Ouest, Tabarre, 3ème Bellevue.

  9. If you click to “Edit” the contact details, it uses the default form found at… appId=referenceapplication.registrationapp.registerPatient …rather than the one I configured. Thus, it doesn’t have the address hierarchy or person attributes. This form also doesn’t properly display the special characters, like item 8 above.

  10. The person attributes that I added to the Registration App are not visible, and can’t be edited anywhere in the 2.x UI. I could create an HTML form that could view them, but there is still not a way to update/correct them.

Thank you @mogoodrich for being my hero and getting us SOOOOO far!

1 Like

We’ve had problems with special characters before, but they are working right currently for us, and we have the same hierarchy as you do, so not sure what is happening here. Could be something to do with the type of character encoding you are using? There’s no client-side error that I’m seeing–is there anything in the server logs when searching for special characters.

Going to your server and looking at the underlying HTML generate, it indeed looks like the configuration of “shortcutFor” and “manualFields” aren’t being picked up, which is the same bug that @mksd was seeing and needs to be entered as a bug.

I don’t think that feature been built yet, unfortunately. You might be able to approximate something by making fields not required… but I’m doubtful.

In your address hierarchy admin section of the old UI, all the fields required are listed as “Oui”… this is what the widget derives required from, I believe.

Yes, you need to modify the XML in the global property “layout.address.format”. Change the “value” attribute for each level to the label you want to display.

Not sure if we support coded person attributes yet.

Hmm, this makes me think there’s definitely a character coding decrepency somewhere between tomcat or the database or somethign else?

Gotta run for now, hopefully someone else can weigh in on #9 & #10.

1 Like

@mogoodrich, thank you again for your persistence in assisting us.

1 and 8 and character issues of 9.) Fixed! There was nothing in the server logs about special characters, when searching for them. I manually specified my tomcat to use UTF-8

<connector .... URIEncoding="utf-8" />

That fixed it, and the address hierarchy started working properly (except for the manualFields). Addresses with special characters that were entered previously didn’t start showing up right, but new addresses that were entered after fixing the connector show up properly. Since we’re not in production yet, and will be cleaning out our patients before going live, we’re all set!

2 & 3.) I have created the ticket for the problem loading in the JSON configuration. @mksd, you don’t need to create it. Please place your vote and add any additional details though. It’s here…

My apologies if I created it in the wrong project; feel free to move it to where it belongs.

5.) It should get it from the address hierarchy as you say, but they are all marked as required, but the UI only actually requires one address field. It seems there may be a bug here? Should I create a ticket? And if so, which project? Registration Module or Address Hierarchy Module?

6.) Fixed. I assumed it wasn’t coming from the address template because they were different between French/English. Putting text in the value field as you mention fixes it to exactly what I want! Great job @mogoodrich!

9.) If I manually change the URL to my AppID, it loads my form, and the address hierarchy works and person attributes section is shown and can be edited.

Anyone have any suggestions for #9 or #10?

Hope you all have a great weekend!