Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Building an OpenMRS Distribution - Lessons from KenyaEMR


Published on

Published in: Technology
  • Rowan - this is excellent! Very clear vision of the components of a distribution. The 'distribution module' idea is a great way of encapsulating the dependencies. Good points about the UI limits for super users. And, a nice summation of the goals of the VM appliance.

    Good luck w/ Nike...!
    Are you sure you want to  Yes  No
    Your message goes here

Building an OpenMRS Distribution - Lessons from KenyaEMR

  1. 1. Building an OpenMRS Distribution Developer lessons from KenyaEMR
  2. 2. Distribution? • Thinking in terms of “distributions” appears a recent development in OpenMRS • Nationwide implementations of OpenMRS are becoming more common (e.g. Rwanda) • Managing 100 sites is a very different challenge to managing 10 sites
  3. 3. Challenges of scale • Need for consistency across site installations • Need for simple or automated upgrades and maintenance • Need for scalable user support
  4. 4. Site inconsistency • What we want to avoid: Site OpenMRS Concepts Module 1 Module 2 Clinic 1 1.9.3 20140714 2.5.3 0.3 Clinic 2 1.9.3 20131215 2.4.1 1.0-BETA Clinic 3 1.9.7 20131215 2.4 … 0.3.1 … • Endless different environments, most of which won’t have been tested • Becomes impossible to manually track
  5. 5. Site inconsistency • More chance of site-specific bugs – Development team might not have tested a site’s particular environment • Complex site-specific upgrade processes – Single components upgraded individually • Confusion for users trained in different environments – National implementations often rely on centralised training events
  6. 6. Site consistency • A distribution should define a consistent environment • We can break that down into components: – A version of OpenMRS core – A set of modules with specified versions – A set of metadata objects • Might be versioned SQL dumps or MDS packages • Might include a separately versioned concept dictionary
  7. 7. Distribution example • An implementation’s own custom modules will only be a part of the larger distribution: OpenMRS MyModule Reporting MyDistro Idgen HtmlFormEntry CIEL
  8. 8. Distribution versioning • Specific versioned releases of all the components make up a single versioned release of the distribution, e.g. OpenMRS 1.9.3 OpenMRS 1.9.7 MyModule 1.0 MyModule 1.1 Reporting 0.8 Reporting 0.8.1 MyDistro 1.0 MyDistro 2.0 Idgen 2.6 Idgen 2.6 HtmlFormEntry 2.5 HtmlFormEntry 2.5.1 CIEL 20120931 CIEL 20140107
  9. 9. Distribution versioning • At every stage of the development lifecycle, we should be working with a version of the complete distribution, e.g. Development with an “in-progress” version mydistro-2.0-SNAPSHOT mydistro-2.0-RC1 Testing with release candidate versions mydistro-2.0-RC2 Installations and upgrades with released versions mydistro-2.0
  10. 10. Distribution modules • Rather than manage a distribution as a separate project, it can be easier to tie it to a “distribution module” • Its version is the distribution version • Defines the required versions of all other components • Depends on all of the other modules
  11. 11. Distribution modules • By requiring all of the other modules the, distribution module ensures that the distribution is always run as a whole <require_modules> <require_module version="0.8.1"> org.openmrs.module.reporting </require_module> <require_module version="2.6"> org.openmrs.module.idgen </require_module> <require_module version="2.5.1"> org.openmrs.module.htmlformentry </require_module> </require_modules>
  12. 12. Continuous integration • Don’t want to develop different components in insolation and only realise integration problems during testing • Developers should work with the latest version of the distribution • CI server should be used to keep a testing server up to date with changes to any component
  13. 13. Buildable distributions mydistro-2.0-SNAPSHOT • Need to make it easy for developers (and CI servers) to deploy a particular version of a distribution • Useful to have a zip archive of the different component modules mymodule-1.1.omod reporting-0.8.1.omod idgen-2.6.omod htmlformentry-2.5.1.omod
  14. 14. Buildable distributions • Maven provides a convenient mechanism to produce an archive of a project with its dependencies – called an assembly • Thus our distribution module can have two build outputs: – A regular omod – A distribution zip archive For an example of how to implement this, see:
  15. 15. Metadata consistency • The idea of site consistency should apply also to metadata • For example: – The distribution does patient registration – This saves encounters of type “Registration” – The distribution can’t function if that encounter type doesn’t exist – Can we guarantee that the encounter type means the same thing in different installations?
  16. 16. User managed metadata • Non-distribution modules often expect the user to manage metadata, e.g. – Every time some code tries to access the “Registration” encounter type, check for null – If it doesn’t exist, show the user an error message to tell them to create it – Tell user to set the mydistro.registrationEncounterType global property to reference the new object
  17. 17. Distribution managed metadata • If we want to be sure that metadata is the same across all sites, we manage it via code rather than users • Distributions should install required metadata automatically • Distribution code should assume that the metadata exists – If it doesn’t, it is a developer problem rather than a user problem
  18. 18. Fail fast assumptions • If we assume that metadata always exists, we should fail-fast if that assumption turns out to be incorrect, e.g. EncounterType ret = Context.getEncounterService().getEncounterTypeByUuid(uuid); if (ret == null) { throw new IllegalArgumentException("No such encounter type with uuid " + uuid); } • Helps developers find problems right away • Easier than tracking down source of a NPE The Metadata Deploy module provides fail-fast fetch methods for most metadata classes:
  19. 19. Metadata identity • Database ids are not reliable for identifying the same metadata in different installations • Anytime distribution code references metadata it should use one of: – UUID: all OpenMRS classes have these and they can be kept consistent across installations – Reference terms: these are globally consistent and unique identifiers for concepts (and soon also drugs)
  20. 20. Metadata installation • One approach is to bundle metadata packages with the distribution and install these on startup • Weaknesses of this approach: – Metadata is not easily readable or editable – Packages typically have to be managed on an external server, exported and embedded into the code – Package installation is slow so usually not appropriate to use the same packages in unit tests
  21. 21. Metadata deploy • Module was developed to address these issues – Allows metadata to be defined in code – Metadata is easy to read and edit – Fast installation suitable for unit tests For more information about the Metadata Deploy module go to
  22. 22. Metadata deploy • Metadata that’s too lengthy to be described in code can be loaded from CSV files etc – Still more readable than zip archives • Support for synchronization of large sets – Used to synchronize OpenMRS locations with all 9500 facilities in the Kenya Master Facility List: • Clean database synchronization: 1min • Subsequent synchronization: 3-4secs • Previous MDS package load: 20-25mins
  23. 23. Concepts? • So far SQL dumps have been best for these: – We don’t manage/edit them directly (we use CIEL) – Database dump is only quick way to install 50,000+ concepts • Groovy script used used to generate XML dataset file of just those concepts used by KenyaEMR – Used for unit tests that need access to same concepts as production environment
  24. 24. Example metadata bundle @Component @Requires({ BaseMetadata.class }) public class MyMetadata extends AbstractMetadataBundle { This “bundle” installs an encounter type and two forms public static final class _EncounterType { public static final String ENCOUNTER_TYPE1 = "d3e3d723-7458-4b4e-8998-408e8a551a84"; } public static final class _Form { public static final String FORM1 = "4b296dd0-f6be-4007-9eb8-d0fd4e94fb3a"; public static final String FORM2 = "89994550-9939-40f3-afa6-173bce445c79"; } @Override public void install() { install(encounterType("Encounter Type #1", "Something...", _EncounterType.ENCOUNTER_TYPE1)); install(form("Form #1", null, _EncounterType.ENCOUNTER_TYPE1, "1", _Form.FORM1)); install(form("Form #2", null, _EncounterType.ENCOUNTER_TYPE1, "1", _Form.FORM2)); // A form that should be retired if it exists uninstall(possible(Form.class, "73d34479-2f9e-4de3-a5e6-1f79a17459bb"), "Because..."); } } Also retires a form that’s no longer needed
  25. 25. Enforcing consistency • Current OpenMRS UI wasn’t made for this idea of a distribution • Ideally we want to prevent even the super user account from doing things like: – Stopping modules – Deleting or modifying metadata • KenyaEMR overrides the regular UI and provides a custom UI without this functionality
  26. 26. Installations and upgrades • OpenMRS itself is usually only one part of a functioning EMR installation • Other parts might be: – The database client and server – The JVM – Tomcat or another Java web app server – Database backup scripts run by cron jobs – Help and training materials
  27. 27. Installations and upgrades • For small or single site implementations, developers often do these • Not feasible for large implementations: – Developers can’t physically visit every site – Sites often have connectivity issues – Upgrades need to be performed by less technical users
  28. 28. Installation via virtual machine • Working installations require correct configuration of all those parts • Easier to configure once at the office than 100s of times at each site • Can build virtual machine images and clone for all sites
  29. 29. Installation via virtual machine • Ongoing experiments with different ways of retaining patient data during upgrade – Moving data from old to new VM via SQL dump – Separate VMs for database (not replaced) and web app (replaced) • Other experiments using bittorrent to download VM images to sites – Works even when connectivity is very poor
  30. 30. Maintenance • Things inevitably go wrong, e.g. – Sites could end up with invalid data due to a software bug – Might need to convert data as software changes • Modules can provide liquibase files to make one time changes – Not always easy or possible to do something with just SQL
  31. 31. Automated fixes • Requiring user intervention should be a last resort • KenyaEMR provides its own automated way of making fixes called chores: – Java classes which perform a one-time job – Run at the end of KenyaEMR startup so have access to all metadata and services See KenyaEMR source for examples of chore classes: e
  32. 32. User support • Need clear processes for issue tracking: – More technical site staff can create support tickets directly in ticketing system – Less technical site staff can use email or phone and then support staff will create ticket • Help materials need to be easily accessible to site users
  33. 33. User support • KenyaEMR integrates with external help site • Users can lookup help documents and videos • Can provide context sensitive help within different apps Help site code available at
  34. 34. Bahati nzuri!