How to use the Address Hierarchy Module with the Reference Application

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!

Hi James,

Some thoughts from our side:

3.) Thanks for reporting the bug, I upvoted and also commented it.

9.) We will start work ourselves on this within 2 to 3 weeks on our own fork of coreapps, hopefully our changes could be adopted by the community later on. There is a double issue in fact:

  1. The "contactInfo" section is automatically picked up by the patient header fragment, but it sticks to the default Registration App’s URL (behind the ‘Edit’ button) rather than understanding that it has been overriden by another instance of the Registration App.

  2. In our opinion, the other sections defined via the Registration App’s JSON should also have a ‘quick display’ with an ‘Edit’ button pointing to the ad-hoc section for edition. Or at least it should be easily configurable to obtain that. So the patient header should understand that further sections exists and provide quick displays and links to the relevant GSP to edit them.
    Note that right now, there is no way to even view those sections (at least in the new UI, we never used the legacy one though). The workaround being to design bespoke HFE forms for the registration custom encounter type that allow edition (and hence viewing).

Thanks @mksd for your insight.

I do hope you can share these bug fixes back into the community.

Hi James.

Of course, we are actually starting work on this literally right now. And I’m hoping that we will have made quite some progress by the end of next week.

We will be working on our own fork of coreapps 1.6 and will submit this via a pull request as soon as we have reviewed the code (and unit tests) and tested the omod ‘enough’. I will ping you as soon as we have got something useable for testing, so most likely in the course of next week. We would love to get your feedback then.

Hi James,

We finally have produced a version ( of coreapps that aims at being consistent with the registrationapp’s configuration on a given OpenMRS instance.

In our version, you can toggle ‘Show/Hide registration Info’:

Our version of coreapps analyses the registrationapp’s configuration and ensures that every section is displayed with its ‘Edit’ hyperlink (and not just the "contactInfo" section as it is done now).

We would love to get other people to test this and provide feedback, and hopefully encourage us to go for a pull request for all of this on coreapps!

There is a limitation though. You will notice on my screenshot that the ‘Edit’ link is missing for the last section: ‘Ethnicity’. This is because, in our registrationapp’s config, this section uses "obs"-type fields. And it turns out that registrationapp’s editSection.gsp (or rather its controller) does not handle that situation. It can handle PersonAddresses and PersonAttributes but not Obs. We prefer, altogether, to conceal the ‘Edit’ button as soon as obs are involved because, to make matters worse, if you leave it, it just behaves as if everything was fine, but nothing gets saved. For now those have to be edited through an HFE form, but at least they display in the patient header with every other sections.

Code here: mekomsolutions/openmrs-module-coreapps

1 Like

Thanks @mksd for your work on this.

Is there any way that you could send me the “omod” so I can try this out?

I believe you should be able to grab it from our CI server, I will send you the link in a private message.

“Disclaimer” This has not been tested much. In fact it has only been tested with our client’s registrationapp’s config. We are really keen on getting bug reports though, before requesting a pull on coreapps.

Remark #1 It is based on coreapps 1.6. That is the coreapps that was shipped with the distro 2.2 (which is the one we are still on). You will most likely not be able to install this on a 2.2+ instance :frowning:

Remark #2 There are other changes than the ones you saw in my screenshot. We have added extension points in two places to allow for customisation of the patient header further. For example, this was requested by our client:

1 Like

Dear @mksd, thank you so much for your work on this! What a wonderful Christmas present. I apologize that I didn’t get time to test this out before now.

As you suspected, it didn’t work with Reference App 2.3.1. I setup a standalone with 2.2, then imported my 2.3.1 database. The address hierarchy last field “broke” when I downgraded, but that was before I added your updated module. I found it to be fully functional on my system, allowing me to edit addresses, with the auto-complete boxes. I also found that I was able to see and edit my custom fields.

The only problem I ran into was with the formatting of the view page when viewing it in French; there is some overlapped text. In English, it wraps the last field to a second line and looks fine. Perhaps if I designed the form in more separate sections like yours it would be prettier.

Also, if the Patient ID stayed on the top line beside the name when the registration info is expanded, that would be prettier.

Please, please please make sure this work gets integrated into the latest versions of the module. If there is anything that I can do to help with this, please let me know.

Hi @arbaughj, nice, thanks for providing feedback! It’s great that you actually tested with i18n using it another language than en-us.

As soon as possible we will upgrade our development platform to the latest Ref App distro, we will then merge all of this into the most recent version of coreapps, solving the problem… and putting us in a position to push this to the community.

I just played a bit with this on my end to reproduce your issues, and I could reproduce both:

  1. The ‘Edit’ button/link overlap when it just goes to the line. We have reused the same HTML structure and CSS as what was there before. Basically copying from contactInfoInline.gsp (the one in use if you look at the community sources.) It turns out that another option is out there, burried in coreapps, but not used from what I can see: contactInfo.gsp. Copying from that one would solve the problem but would also imply a visual design change. The ‘Edit’ link would always be in the same right margin, regardless of the amount of data on its left hand side. Like this:

    But then the widest line determines where, on the right side, all the ‘Edit’ links will be aligned. It may be impractical in some cases, but the issue you experienced would not occur anymore. However I find that, when using this HTML layout, one tends to click on the wrong ‘Edit’ link as they are not quite aligned with the data they are meant to edit.

  2. The patient ID widget not staying at the top. This is trickier and I am not sure exactly why this happens but clearly the existing structure doesn’t quite work in cases when more than the whole width is filled up. I mean it works, but the identifier gets moved down. I think we should live with that one and raise a bug later if that is ok with you.

Although I agree with you that none of the two above should happen, you may indeed be able to simply avoid it all by creating more sections with less data in each section, as you suggested. It seems that you could do something like we did and split your configuration with a ‘contact info’ section and a ‘next of kin’ section. Would that be an option for you?

Thanks again very much for your feedback.

1 Like

That sounds great!

Please let me know when you’re ready for me to test the latest Ref App version.

I am also interested in the module that lets you edit what attributes to show when viewing a patient, I would be grateful if you could provide the .omod, thanks @hpardess


That’s the one: RA-1350: ‘Edit all the information inserted in Patient Registration Form’ @hpardess, are you considering starting work on this?

I haven’t started to work on this task yet. I was busy on site with other client requirements. I will let you know when i get ready. :slight_smile:

@mksd am trying to get some one to work on this. Do you happen to know where this code moved?

As is it now, Registration App generates by default a Registration Summary config that follows the sections of the Registration App config. Meaning that you can always access all the sections in edit mode that are part of the Reg App config in the first place. See:

  • RA-1425 - Registration summary page to display all defined sections of the Registration App

I don’t remember though if the link to the registration summary is automatically added to the patient dashboard, maybe not… @ruhanga?

At the time of merging RA-1425, a custom configuration reg app containing the summary sections link was used. Merging RA-1426 solves this issue.