O3: Address Hierarchy widget plan

So this week with the #ethiohri team (inc. @ICAPEthiopia & @UCSF), we need to create a solution for address hierarchy in 3.x. Specifically, the need is for a UI that could be inserted pretty much anywhere (though mostly in forms) to help the user specify regional specifics in cascading order of specifics. And, the labels are also specific - ET is divided into Regions, then Zones or Sub-Cities, and then Woredas.

I discussed with @dkayiwa, @samuel34, @dagimm, @eudson, & @mayanja, and here’s our plan:

  • To leverage the existing backend provided by the Address Hierarchy Module
  • To build this feature as an esm-app
  • That esm-app should be embeddable within any form. Should be able to be engine agnostic (ie. could be using the Ampath form engine or OHRI form engine). @samuel34 knows a way that the schema should be able to declare a widget within the form. (Samuel can you remind me how this is done?)

Requirements Wiki page: 3.x Address Hierarchy Widget - Projects - OpenMRS Wiki

Does anyone have any feedback, thoughts or concerns?


Ps we will try using initializer to import the metadata for /addresshierarchy

@grace it turns out that it’s not Iniz but the AH module itself that loads the content of configuration/addresshierarchy.

A bit as oddity today, but at the time (2017) @mseaton and I were pondering the idea that each module would take care of its own metadata… this was never migrated to Iniz and remained in the AH module.

1 Like

Update: Here’s our Requirements Wiki page: 3.x Address Hierarchy Widget - Projects - OpenMRS Wiki

Current design vision is something like this:

@mksd this comment was actually so helpful because we couldn’t figure out why the ICAP team’s previous attempts to use Iniz to support Address Hierarchy weren’t working! I kept searching the Iniz ReadMe for any additional documentation re. /addresshierarchy. I’ll add a blurb about this there now. :wink: → Done: Added explainer for Address Hierarchy by gracepotma · Pull Request #188 · mekomsolutions/openmrs-module-initializer · GitHub

This is a great idea! However, the third point here is actually pushing us to a place where we should start to make real technical decisions around both the form schema and the form engine before things diverge too far. Ideally, instead of trying to build some custom widget that can work in any form engine, we should come to an agreement on a form engine. (Any custom widget like this will likely require per-form-engine extensions to ensure it’s plugged into the form engine in a way that the form engine can understand the input into the component and correctly translate it into whatever underlying representation is necessary).

1 Like

Update: Progress shared by ICAP-ET team here: O3: Autocomplete Component (searchable dropdown) - #5 by sinte


Hi all, @sinte @dagimm @mksrom @ibacher @eudson @alaboso: We are at a blocker-crossroads with Address Hierarchy for O3.

Really nice recent work on this PR by @sinte - so awesome to have this progressing and this will be leveraged by so many teams world-wide. :world_map:

However changing the structure of the XML template file caused a highly impactful breaking change to all other O3 teams using the registration page. But what’s great is this helpfully exposed an API gap we had overlooked.

Thank you to @ibacher for clearly defining the REST API work needed to allow us to leverage the AddressTemplate class: [RESTWS-892] Add an endpoint to expose the AddressTemplate via REST - OpenMRS Issues

This should unblock everyone affected - from OHRI to ICAP to Mekom and all their customers etc.

But we need a senior-ish dev to pick up this ticket (RESTWS-892). Any ideas? :pray:

1 Like

I noticed that @abertnamanya took this up and is waiting for @zacbutko to provide a link to the xml template.

1 Like

@dkayiwa unfortunately I don’t know about the history or desired structure of address template XML other than what is already posted on the wiki Administering Address Templates - Documentation - OpenMRS Wiki . Hopefully this is helpful

Discussed w/ @dkayiwa and he is going to take up this ticket <3 Assigned to him accordingly.

Thanks @grace, Sorry had not yet started on this ticket. But this is good that Daniel is taking it up.

1 Like

Can be accessed as: https://qa-refapp.openmrs.org/openmrs/ws/rest/v1/addresstemplate


:tada: :fireworks: :muscle: Wow Daniel, A+++ for turnaround time, seriously!! :smiley: :smiley: :smiley:

Sorry for silly question but… What’s the next step now?

Do we need a platform minor-version release?

And then, @ibacher - would you recommend that @sinte leverage this new API in his code instead…?

No. The changes were in the rest webservises module, which we can release with a click of a button on bamboo. But even before the module is released, there is nothing that prevents a developer from leveraging the new API, because it is already available at: https://dev3.openmrs.org/openmrs/ws/rest/v1/addresstemplate

1 Like

Yes, we should absolutely use that API instead of directly parsing the XML.

1 Like

@sinte are you okay to do this? CC @dagimm

Hi Grace,

Most of the folks from our team, including Sente, are on leave and will be back end of September.

What is the priority level for the task?

1 Like

Thanks Dagim! (especially since I think you submitted this while on leave yourself!)

@mksrom what’s the priority? I believe the org with the most urgency around the breakage the PR caused is Mekom. If the priority is urgent, perhaps someone at Mekom could tweak/patch that original PR work to leverage this new API endpoint?

So, at this point the O3 patient registration address is broken, so it needs to be fixed asap.

There are 2 underlying issues:

  • The address template was not used properly (thus the need to provide a real endpoint for this so that devs don’t misuse the address template in the future)
  • The commits made have removed support for non-Address Hierarchy-enabled implementations. Since many implementations are not using AH it was a mistake to merge code that breaks the standard/base address entry. AH support should be made configurable.

What we must do now is to revert/disable the current AH support and let devs fix the code and make it configurable. @ibacher had mentioned he’ll be able to do that.


@vasharma05 can you remind us; how did this get resolved? There is config for AH settings now, right?