Saturday, August 19, 2017


In the previous post, we discussed the rationale of using the HL7 Reference Information Model (RIM) for our primary information model in OpenIZ, in this post we'll explore how OpenIZ exposes core data via HL7 FHIR.

While the RIM is used as an information model in the solution, the RIM is (unfortunately) quite verbose for expression over the wire. Anyone who has implemented HL7 CDA or HL7v3 will tell you this. That is why we only expose the RIM over REST whenever another system requires 1:1 representation (like the disconnected client).

For most other interactions with the IMS, HL7 FHIR is quite capable. It allows third party developers to access the clinical information in the IMS without having to worry about the complexities of the RIM (what is a mood code anyways?).

The OpenIZ implementation of HL7 FHIR has focused primarily on read-only transactions. The rationale for read-first focus is that quite a bit of work has to be done to ensure that data written using FHIR will comply with the RIM.

Currently OpenIZ supports the following resources on our /fhir interface (all are STU3):
  • Immunization - Which provides query access to vaccination events in the IMS
  • ImmunizationRecommendation - Which allows FHIR clients to execute the care planning service
  • MedicationAdministration - Which provides query access to non-immunization medication events such as supplements.
  • Observation - Providing queries to observation events (both coded and quantitative)
  • Patient - Allowing for the querying of patients in the OpenIZ system
  • AdverseEvent - Which provides facilities for querying Adverse Events Following Immunization (AEFI) events
  • AllergyIntolerance - Providing access to problem concern or allergy information in the IMS
  • Condition - Which allows fetching of clinical conditions, reactions, symptoms, etc.
  • Location - Providing complete access to places stored in the OpenIZ IMS
  • Medication - Which allows querying for individual medication lots in the system
  • Substance - We've mapped substances to the type of substances which can be encountered in the IMS.
  • Provider - Which maps to the physicians or clinicians which provide care in the IMS
We hope to provide additional resources (especially infrastructure like conformance and value set) in the coming months. Look for OpenIZ at a FHIR connect-a-thon soon!

Friday, August 11, 2017

Why did OpenIZ use the HL7 RIM?

One of the questions you might be asking yourself is: Why on earth, would the designers of OpenIZ use the HL7 RIM (Reference Information Model) as the basis for the platform.

It is true, there are alternatives to using the RIM as an information model including HL7 FHIR, HL7 v2, OpenEHR, custom model, etc. So, I thought since it is Friday, it would be a good time to do some explaining of why the OpenIZ data model is the way it is.

So, why the RIM?

Good question, at a high level:
  • The RIM is very expressive, it allows us to represent a variety of use cases outside of immunizations. Often, countries will try to leverage investments in one programme area for another purpose, and Immunization is no different. When you think about it, Immunizations are just a part of child care, and child care is really a part of maternal and child care, and maternal care is part of patient care. The key here is we wanted OpenIZ to be patient centric rather than programme centric .
  • The RIM saved us time (that might sound like an weird statement given the common complaints about HL7v3). By leveraging the RIM, it already gave us a logical construct to work within, there are literally thousands of pages of documentation on the RIM, and this really saved us having to invent our own way of doing things.
  • There are a ton (probably a metric tonne if we printed it out and weighed it) of documentation surrounding the RIM, and there are lots of training materials for the RIM. These training materials can be adapted for OpenIZ relatively easily.
  • We probably would've come up with something not as good or similar anyways. Given the fact that we wanted a patient centric record for immunization, and the fact that there are probably millions of person-hours of effort put into developing the RIM, we felt that this analysis wasn't worth reproducing.
  • We felt like we could simplify the RIM, since we have extensive expertise in HL7v3 we felt that the pain points of the RIM could be optimized and made less painful. Also the advent of better tooling and better wire level formats would assist in this.

Things we took out:
In order to make the RIM a little more bearable, we had to take some things out, this is a high level..
  • Roles - This is perhaps the biggest change we made to the RIM. OpenIZ's data model is based on Entities Participating in Acts, whereas the RIM is Entities playing Roles Participating in Acts. Why did we take out roles? Well, after some careful discussion in the team we determined that there was really no need given the use cases to differentiate between Bob the Doctor and Bob the Patient, we just create two entities (even though they are logically the same entity, the benefit of this added join just added complexity).
  • Procedures - One of the major classifications of Acts missing in OpenIZ is Procedures. The reason for not including these was simply a matter of resourcing, we didn't have sufficient resources to put into developing this Act type given the other pressing concerns. Procedures are on the roadmap for OpenIZ in the future, as we definitely want to allow people to record procedures done to the patient.
Things we added:
Not everything was an exercise in removal. We've adapted the RIM to include some concepts from FHIR as well.
  • We added versioning to Acts and Entities which means that instead of using Replaces relationships, we just version the entity and  act independently of the entity or act relationships. We still have entity relationship of replaces but that is now used for merging.
  • We added the concept of Extensions and Tags. These are taken from FHIR. An extension defines a versioned piece of data about an entity or act, that is creating a new extension creates a new version of the entity or act. Tags on the other hand, allow for non-versioned tags to be attached to an object.
  • We added the OpenMRS concept dictionary data model to the RIM. This gives the information model a little more flexibility in terms of using concepts in the context of the RIM. This is a huge shout-out to the flexibility of the OpenMRS concept dictionary information model which separates the logical concepts from wire-level reference terms.
  • We added some proprietary schema tables around consent and permissions. This was borrowed from IHE XDS' view on confidentiality. Rather than tagging a code as in the RIM for privacy, we allow the associating of security policies against an object.

Thursday, August 10, 2017

OpenIZ SDK & Disconnected Client for Linux & MacOS

In case you didn't notice in the latest release: there are SDK and GTK+ based client for OpenIZ on Linux and MacOS. These two programs are currently under heavy development and we expect to be shipping them soon.

Currently there is a preview of the Linux & MacOS SDK in the Edmonton CTP4 install ( These are distributed in tarball format for the time being, and work in a fashion similar to the Windows SDK. All you need is the Mono Framework installed and you're good to go.

We are also working on DEB packages for Ubuntu and derivatives (I personally use Xubuntu to develop on). Unfortunately due to the heavy focus on deployments at the moment by the core team, these packaging efforts have been put on the back burner, but we're hoping they'll be ready for the Edmonton release in September.

Ubuntu Packages

Starting with the (Edmonton CTP4) release of OpenIZ Disconnected Client, there are now packages for Ubuntu. This package will install OpenIZ Disconnected Client in the appropriate directories with any prerequisites, and will also create a handy icon in your launcher.

Here are some screen shots of the Linux version in action running a prototype of an implementation of OpenIZ.

A sample of the encounter entry screen showing disease surveillance entry.

Clinic inventory graph grouped by total stock for each type.

Tuesday, August 8, 2017

Diving into the OpenIZ SDK

The Edmonton release of OpenIZ is fast approaching and there are now several iterations of the previews on our downloads page. Many have started to ask how to get started with developing OpenIZ applets and how to debug them. This post will hopefully provide a brief overview of what is in the new SDK.

For this post, I'm going to be using the Community Technology Preview (CTP) 4 of the OpenIZ SDK. This will be released around Aug 11, 2017. Once installed, you'll notice a new program group (or new icons in the existing Open Immunize program group):

Business Rule Debugger

The business rule debugger does exactly what it claims. It allows you to debug basic business rules on your system. The current iteration of the business rule debugger requires you to create an openiz.exe.config which is required to debug server side execution of business rules. In CTP 5 we plan to make this requirement optional by providing the SQLite version of storage by default.

Clinical Protocol Debugger

The clinical protocol debugger is used to debug the clinical protocols you can create in your application. It functions in an identical manner to the business rules debugger and also requires an openiz.exe.config file to be present (in the current version). There is a tutorial on how to write these business rules on the github page, it also introduces the debugger.

Log Viewer

The log viewer is a tool that can be used to easily sift through the sometimes large log files that OpenIZ and OpenIZ Disconnected Client generate. It provides basic search functionality, filtering by source of the log and also allows you to look at "thread neighbors" (that is, log entries which were generated by the same thread only, so you can follow). 

Brain Bug

The brain bug tool provides a series of utilities that allow you to easily extract android data from tablets (yes it is named after the Starship Troopers "brain bug"). Using the brainbug tool you can easily extract adb backups on windows (not that easy since the backups are zlib compressed and aligned). 

Applet Compiler 

The applet compiler is used to compile your applet source code into a single PAK file which can then be uploaded to an active OpenIZ server and tested. The applet compiler allows for the generation of unsigned, and signed pak files using a variety of compression schemes (depending on the size of your applet source).

Mini IMS

The Mini IMS is a tool that allows you to easily debug your applet source code in an environment that exactly mimics the tablet and disconnected clients. Here, there is no need to compile your code into a PAK file, rather the Mini-IMS will simply read the directory structure of your applet source code as though it were compiled. 

A few things to note with the Mini IMS, first is that you should never accept updates when prompted (it will clobber the session loaded files). 


In the previous post, we discussed the rationale of using the HL7 Reference Information Model (RIM) for our primary information model in Ope...