What's your vision for the OpenMRS Reference Application?

@darius, @jteich, @lober, @mseaton, and anyone else with an opinion,

Can you provide a high level (brief, less than 400 words) vision of what the OpenMRS Reference Application should be? Stay at the high level – i.e., what are the 3-4 key goals/features to consider? Just your own view/opinion.

We will be making strategic decisions on this starting with the 4-Feb-2016 Leadership Call, so any input you can summarize soon would be incredibly helpful in guiding our discussions.

Some relevant quotes to inspire you:


“If two men on the same job agree all the time, then one of them is useless. If they disagree all the time, then both are useless.”

–Darryl Zannuck


“A complex system that works is invariably found to have evolved from a simple system that works.”

–John Gaule


“That was done differently by three different people, two of which were me.”

–Darius Jazayeri


@mseaton you too

Here’s my 2¢:

  • The reference application is an example of what can be done on the platform (our demo server, a place to demonstrate how to use new features, demonstrating best practices, a place we can build toward consensus).

  • Constructed in a way that can serve as a starting point for implementations (i.e., take the refapp and add/remove functionality to meet your needs).

  • The architecture should be technically forward-thinking – i.e., Angular+REST ± OWA built from Bahmni or similar.

  • Driven first by implementation needs and secondly from working along a road map of a “complete” application.

  • Not a distribution. The reference application can be useful even if an incomplete application. If/when we reach “complete” functionality, it might be easy to spin off a version of the Reference Application as a “Community Distribution”


and mine:

  • Agree that it’s an example - an example of what can be done, and example of how to use the platform for the basic medical record functions - manage a set of patient identities and record clinical information about those patients.

  • Agree that it is a starting point for implementations - as such it should be complete (start to end) at the expense of being richly featured.

  • The architecture should be technically forward-thinking, and a primary goal is to allow it to continue to grow and incorporate demonstrations of new technologies. That’s a little bit different from the paradigm of building an “it” - perhaps more of building an activity.

  • Driven first by the need to have a community owned, community developed example of how to use OpenMRS, and secondly by the individual road maps and goals of those contributing to it. Just as PIH evolved the current RA into something they could use operationally, but no longer spent the time contributing back to the RA everything they did, the new RA would be basis for distributions, but not anyone’s “end distribution”.

  • It is also an example of a distribution. It should be a complete application, small enough that the whole distribution process can be illustrated through the RA, by community effort. There should be an RA roadmap, RA documentation, an RA release schedule — all of the stuff mentioned in the operation plan is important. The RA (even if functionality is necessarily abbreviated by resources available) should be the “community distribution.” If the community gets behind that distribution and adds more functionality, then the community distribution will become more richly featured and applicable to a broader range of use cases.


Lot of good points above. I would agree with many; here I will emphasize the Ref App’s value in keeping some consistent application structures as a home for core, reusable basic application-level structures

  • It is a starting point for implementations, as described above.

  • It contains basic core application-level modules such as drug ordering, notes, allergy entry, test results, perhaps more advanced but widely-valued things such as flowsheets and immunization records. It reduces the need for rebuilding in each implementation, propagates useful functional innovations across current and new sites, reduces the structural divergence that would otherwise happen with those varying implementations, and ensures that core services such as security, reporting and clinical decision support can be largely reused from one site to another.

  • It (eventually) could be a basic usable turnkey distribution for implementations that don’t have access to development resources. It does not have to be complete in the immediate future, but incrementally gets closer to being a complete basic application.


I agree it should be an example that shows the best practices for building an application on top of the platform. It should also be extensible - meaning that components (modules/apps) can be removed or added. Additionally, I think it should actually be usable in production for a few use cases that we decide on.


Here are my $0.02…

I agree, the Reference Application should be a starting point for implementations. It can be downloaded and used as-is by institutions with limited development resources, or extended by those that do. It should be the go-to standard of what OpenMRS is. FYI: we are “shooting our-self in the foot” (inhibiting new implementations) by instilling the idea that you must do programming to implement OpenMRS.

I agree, it should contain basic core application-level modules as @jteich explains.

Ideally it should be driven by what smaller institutions need for basic functionality. It should support custom forms and custom reports that can be created by implementing organizations and shared between them.

It would be nice if the Reference Application defined a series of best-practice hooks that modules could be plugged into that would work across distributions. For example, a concept management module or vaccination module could work on Reference Application or on a distribution (like Bahmni). The same way as you can run the same apps on different versions of operating systems.


i agree with the concept of core functionality. There are many clinical reasons to have that; one of the most important is patient safety. There are best practices for using interfaces to decrease the risk of medical errors; having a reference application that embodies those best practices that can be used as a starting point will help decrease errors, and, if done well, improve efficiency. It isn’t reasonable to expect that most developers ( who may or may not have ever developed HIT software interfaces before) understand and/ or know these standards.

1 Like

I also agree with core functionality – I think the issue is “how much is core”, and what tradeoffs are needed. Looking at the thread above, I proposed a pretty minimal list of core functions - they boil down to being able to easily deploy a secure system that can track and manage patient demographics, and that can record clinical observations associated with the visits of those patients. That very minimal system needs to be a “complete” distribution - that is, it should have documentation, be deployable, installable, modifiable, and revision-controllable. In otherwords, someone should be able to get it, get it going, and get excited about what they can do with OpenMRS.

The reason I want that list to start out with such a minimal specification is that @darius cautioned quite appropriately that there was no $ or people to maintain such a system, so it would have to EITHER be very low resource, or be a system someone else was building for their own purposes.

To me, the community ownership part is important, so I’d err on the side of being too simple, and ensure that it could actually be built. I’d hate to err on the side of being too functional, and winding up with the community following along in the wake of a particular developer or use case.

@jteich made the excellent point that the system should be far more complex - that it should have rich features to be a true test bed for innovation (to paraphrase).

@mseaton made the point that it needs to be at least a complete set of the functionality of the current RA.

For me personally, I’d rather we start small and exceed our expectations, keeping this at a scale where the community can retain the lead, even if it initially falls short of these last two goals.

1 Like

I won’t re-iterate all of the points above, most of which I agree with. I’ll say only a few things where I feel there is the most divergence of opinion.

@lober said that I made the point that “it needs to be at least a complete set of the functionality of the current RA”. If I said that, what I was highlighting is that the legacy 1.x application which was long distributed as the “reference application” has been used in production as a basic EMR system by many implementations and still is today. And as @arbaughj and PIH implementations in Lesotho, Malawi, and Rwanda can attest - this system (although certainly not pretty) - has enabled them to get an EMR up and running and supporting their clinical programs for many years despite not being a feature complete point-of-care EMR.

What I think made the above so successful, and the primary things I want to maintain, are:

  1. That this core application could be easily extended by modules at known extension points
  2. There was a standard set of reusable components (eg. portlets, css styles, js libraries) that were published by the core application and which anyone writing module extensions knew to use to ensure overall application consistency
  3. The features that we included intentionally sacrificed content for configurability (eg. implementers could add their own forms with htmlformentry or xforms and, theoretically, get data back out with the reporting module).

Whether or not we make the reference application a “distribution” or make a derived “community distribution” based on the reference application, I think that OpenMRS should release a distribution that honors the above legacy (and does it better). It may not be feature complete, but it provides a foundation, is highly configurable, and can be used in production without qualification.

Ideally, if we do this well enough, all of the other distributions that evolve will do so on top of this shared platform, not in parallel to it, and we will all benefit from that work much higher up the stack.

Mike (343 words)


(I haven’t read the other comments yet, because I wanted to come at this with a clean mind, so here is one post, and then a second to respond.)

Here’s my take on the Reference Application (in fact I prefer to think of this as the “Community Distribution” rather than as the “Reference Application” but that’s a tangent).

Background drivers:

  • Lots of growth in the ecosystem, and lots of new thinking about Distributions and Service Providers
  • particularly, as the community we have failed to build a complete out-of-the-box product, but others are succeeding at this, so we should focus on our comparative advantage.
  • Too many things happen in too many places for us to be able to coordinate them much. We could leverage lots of little bits of worldwide effort, but only by lowering our expectations for central coordination, and consistency.
  • There are hard tradeoffs between an open community process that lets new developers make meaningful contributions, and the most professional/consistent product.
  • Strategy is deciding what you will not do.

What values should we prefer

Since this is really all about tradeoffs, I have phrased these in the A OVER B style of the Agile manifest. It’s not that the second thing is bad, it’s that given a tradeoff I think we should prefer the first:

  • Demonstrates new functionality quickly OVER the best possible UI
  • Very customizable OVER easy to configure
  • Built out of reusable components OVER easy to configure and best possible UI
  • Includes opinionated starter sets of metadata (common allergens, WHO essential drug list, etc) OVER the ability to work with any possible metadata configuration
  • alternately: minimally works out of the box OVER full customizability
  • Deep functionality where we can be opportunistic OVER complete feature set
  • Low bar to community contributions OVER consistent and well-coordinated user interface
  • Ability to add new features OVER backwards compatibility with refapp-derived forks
  • Do the most with few FTEs OVER professional/consistent/reliable out-of-the-box application.
  • alternately: Frugal development OVER a polished product

In practice

In practice I think this means:

  • the goal is not to achieve the largest possible install base for the OpenMRS Reference Application, but rather to catalyze implementations, distributions, and service providers to do the most possible good work.
  • we should not try to build a huge central team to build a polished product, but optimize to demonstrate the most we can with limited and loosely-coordinated resources
  • we still need a large enough core set of devs, BAs, and PMs to catalyze external work
  • whenever a new feature is built in the Platform, or designed through a community process, we aim to coordinate community developers to build a demonstration example of it quickly
  • when we see something interesting and applicable that is done in an implementation, we should coordinate community developers to fork/copy it
  • and relative to today, we act a lot less picky about what quality some feature has to have before we’d harvest it

@mseaton @jteich @darius - apologies (of course) if I misquoted anyone.

Mike - I particularly like your comment about distributions evolving on top of the RA, rather than in parallel. It seemed to me that deliberately keeping the scope simple would facilitate this by avoiding the initial bundling of complex features representing the vision or requirements of a single group or use case. I like your 3 points regarding extensibility and reusability at the RA level.

Darius - Good listing of tradeoffs - I was trying to get at some of them, but in a wordier. I think that picking apart these values and looking for consensus might be a great way to proceed. For instance, looking to see first a) if there is agreement on what the terms mean “best possible UI”, and then b) if there is agreement on the tradeoff. I think for a minimal RA I’d reverse some of the tradeoffs, or add others - Shallow, complete functionality OVER deep functionality. Easy to configure OVER very customizable (though ideally that’s not a direct tradeoff - maybe examples/agreements on meaning?) etc. Some I agree completely with Novel/Simple/Meeting Goals of RA OVER backwards compatibility Some I’d twist - my cornerstone has been to advocate “frugal-complete” OVER “ambitious-polished-example” So I really like the method you chose and it might be a way to arrive at consensus.

Some of where we go may be as simple as what resources support the vision (or different resources available for different visions…)

And the interesting thing is that I really agree with the “in practice” section - pretty much verbatim - so I think it’s really about how to get there, not where to go.

Jonathan - I like the modules you listed - and I think that developing them as modules on top of a very basic set of functions is in line with the strategy Mike espouses.

1 Like

@mseaton you summarised my thoughts so perfectly that i have totally nothing to add! :smile: Whether we call it reference application or distribution, i do not care. All that matters is having something that meets what you summarized. That will be good enough for the Uganda sites that i have seen.

1 Like

My vision for the RA is “The giant on whose shoulders the rest of the OpenMRS community stands on to build their implementations and customizations”.

However this puts additional pressure on the architecture of the RA that to be modular, closed for modification but open for extension with nothing being “final” but can be replaced, pulled apart at a whim.

1 Like

I wanted to thank everyone for their fantastic input thus far. For everyone that is curious as to why this conversation topic has come up: we are in the midst of defining our strategy for the next couple of years. One of the aspects our strategy is focused upon development of a “reference application”, which is (and I quote):

Develop and evolve the OpenMRS Reference Application, a community-managed OpenMRS Distribution, which serves as:

  • an application meant to be configured and used directly in health delivery settings
  • a demonstration of the capabilities of the OpenMRS Platform

In the midst of trying to operationalize this work in a plan, the leadership team has recognized that details matter, and we weren’t really clear on the specific targets of this work. In other words, we seemingly hit an impasse.

We must get to consensus on a starting point for this work.

Reading through thus far, I think there is general consensus around the following concepts:

  • A starting point for new implementations, which simultaneously serves as an example of the platform and what OpenMRS is capable of
  • If we’re lucky, it could also become something feature rich and “fully functional” over time… but that’d be a product of an iterative, community led process over something developed as a waterfall-type design
  • Functions need to be designed in a modular way, so that they could be turned on and off. These functions link into the application through extension points.

I still think there’s a need for greater clarity around the following concepts:

  • What stakeholder group is designing and prioritizing functions? On one extreme, there’s an expert panel of the best, most experienced developers of record systems sitting up on high and declaring how to build things for the world to benefit. This maximizes the potential for best healthcare practices to be driven into the community, and arguably is a way to ensure patient safety. On the other extreme, the users are in complete control of the process. What they say goes, and the rest of the community humbles itself to follow the lead of their needs. Experts are participants and advisors, but not calling the shots.

  • What is complete? In this thread are multiple perspectives. Some have suggested that complete is their individual perceptions of a fully functional EMR, others have suggested that complete is what’s in OpenMRS 1.x RA, others have suggested that complete is not the goal at all. That complete might come as a happy outcome of community will, and emerge based upon use.

  • How to lump and split application modularity? I’ve read on this thread that the modularity exists at the clinical application level (i.e., order entry, retrospective clinical flow sheet, etc), and I’ve also read that it exists at the technical functional level (i.e., a form collection widget, a calculation widget, etc). I’ve watched projects do the former, and recreate base functions in each component… and I’ve watched other projects build an entire order entry system on a simple form collection base functionality :slight_smile: )

I want to time box this conversation and get to a first iteration of a plan by February the 12th at the very latest.

Please approach this knowing that we won’t get the plan perfect. We’ll come back to it again next year!

(over 400 words)

one comment about design/ patient safety and usability:

one way to address this is to develop recommended standards and conventions (SAC) for the GUI design work; sites/ programmers could take or leave them ( depending upon where we end us in this discussion) but we would have done our due diligence to ensure that these principles are available and communicated. We could think of them as extending the digital principles that OpenMRS endorsed last year.

I see some common themes…maybe, but I’d like to ask specific people a few questions before I try to summarize them.

Also, it would be helpful for people who haven’t already done so to say what we should NOT focus on, in order to achieve the things you’ve said we should. :slight_smile:

@lober, @burke, you’re both saying that we discard the Legacy UI and Reference Application 2.x and build something new from scratch with modern technologies (or maybe build on top of Bahmni). This means a “Reference Application 3.0” which will drop compatibility with prior work, right? Would you say “modern tech stack OVER preserving compatibility with things like HTML Form Entry and XForms”?

@lober, @pascal, @arbaughj, you all want something that works out of the box for some use cases. Pascal and James, do you agree with Bill’s minimal statement of Registration, and (Visit) Form Entry as an MVP?

@mseaton, @dkayiwa: “other distributions that evolve will do so on top of this shared platform”…do you agree with Burke and Bill’s comments about going to a modern tech stack? Are you saying that we should go back to a world where HTML Form Entry and XForms are king, or that we should build new technologies like them?

Thanks @darius for coming back to us for clarification! Concerning your question…

I would say the features/functionality of the Legacy UI (before Order Entry was removed) should be the minimum of the Reference Application. Otherwise, it doesn’t meet the needs of existing implementations to be able to upgrade to it and continue to breathe life back into the community.

I also wholeheartedly agree with @mseaton when he says…

I think registration + form entry + reporting would be the MVP. What’s the use of entering data if you can’t get it out? Disclaimer: I’m not a clinician.

Also, I think @arbaughj brings up a great point that I avoided mentioning at first:

This is not easy (to put it lightly), but if we effectively end-of-life every existing implementation using the legacy system, I think we might be making a mistake.

I’m all for a modern tech stack, and have been really impressed by the work that has gone into the owa stuff. REST is clearly strategic. I don’t know that this is necessarily incompatible or mutually exlusive to htmlformentry and xforms, though I agree that major rework would likely be necessary and alternative new approaches to meet a similar need will likely be preferred. I am not advocating that we hold onto older technologies for the sake of it by any stretch. But I’ve also seen enough Angular (and javascript code in general throughout the OpenMRS ecosystem) that I do not necessarily see this as a panacea. If our “modern tech” does not allow us to do what htmlformentry and xforms can do, then it is not an improvement.

1 Like