Friday, February 16, 2018

Getting Started with the OpenIZ SDK

Ever wanted to get started developing your own plugins for OpenIZ but don't know how? Well, this handy video on YouTube guides you through the process of setting up your machine & toolchain for OpenIZ development.

There will be some more exciting news coming soon! OpenIZ is about to undergo a major transformation and we are very excited!

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). 

Wednesday, July 26, 2017

Compression / Optimization in OpenIZ

While deploying OpenIZ in a rural region of Tanzania, some of our users were noticing that initial synchronizations were taking quite a long amount of time. The users were attempting to download over 30,000 records over a 2g connection.

To begin with, the Edmonton CTP version of the OpenIZ IMS (0.9.6) did have some greedy database queries. After optimizing the server down to near 0 response times (using REDIS for example, first request for 5,000 facilities is about 20 seconds, second request for the same dataset is 1.5s), I decided it would be worthwhile to update the compression on the OpenIZ IMS.

After reading on the internet, I found some articles about SharpCompress (MIT licensed) which I could use to extend Edmonton CTP's compression providers. The deflate and gzip (compressors in SharpCompress were apparently faster than the default .NET ones). After some work, there are now four compression schemes supported for retrieving and sending data to the OpenIZ IMS:
  • LZMA - The compression scheme used by 7z, which can heavily compress data however requires quite a bit more resources (decompression does not)
  • BZIP2 - A burrows-wheeler compression algorithm which yields slightly higher compression rates than GZIP but is faster than LZMA
  • GZIP - The GNU Zip format, this is standard HTTP GZIP compression
  • Deflate - Again, standard deflate compression algorithm, OpenIZ uses the optimization for speed rather than compression.
Each one of these compression schemes is now supported in the Disconnected Client (Edmonton CTP3, they will require a server running Edmonton CTP3 as well). The settings are found in the "Network Options" section of the configuration UI.

For those that are interested in the trade-offs in terms of speed and bandwidth usage, I setup a small facility with 500 patients and downloaded the data. Please note that these are very specific to this particular use case, however are a good guide. Below are the results:

Algorithm Download Time Size
Broadband DSL 56k (like 2g)
LZMA 0:18.50 1:14.50 5:30.00 1.8 MB
BZ2 0:18:50 1:18.50 6:01.00 1.94 MB
GZIP 0:19.00 1:20.50 6:30.00 2.1 MB
Deflate 0:10.00 1:40.50 6:45.00 2.2 MB
RAW 0:08.50 5:00.00 24:50.50 8.3 MB

The differences in these results are more marked when dealing with larger clinics with 10,000's of patients and 100,000's of results. This illustrates the need for connection compression. The OpenIZ IMS always supported the submission and querying of data in compressed format, with these new schemes, it makes downloading a lot faster on 2g connections!

Sunday, July 23, 2017

OpenIZ Disconnected Client Community Technology Previews Released

Well, after about two years of toiling away, the team at MEDIC has finally released the OpenIZ Disconnected Client. As of this writing you can find the Community Technology Preview 2. There will be more coming soon, but for now you can access:
  • The Disconnected Client Vanilla Application
  • The Software Development Kit (SDK) for writing your own applications
  • Some tutorials and wiki articles (more are coming)
  • The OpenIZ IMS Server

Disconnected Client

The disconnected client is the user interface for OpenIZ. The disconnected client is a complete clinical software solution that does not require internet and can operate for days or even weeks without connectivity before synchronizing its local data to the server. All business rules are executed locally, so even server logic operates on the client.

The disconnected client works on
  • Microsoft Windows 7+ Operating Systems with .NET 4.5.2
  • Android 4.4 Tablets (running System Web View 44 or higher)
  • Ubuntu Operating Systems with Mono 4.x and GTK+
The main features that work for this CTP release of the Disconnected Client are:
  • Synchronization and conflict resolution with an OpenIZ IMS server
  • Over the air updates of applets, rules, reports, and protocols
  • Offline reporting engine
  • OpenIZ's care planning engine
  • JavaScript business rules engine
  • OpenIZ JavaScript bridge 0.9.8 (allowing you to query the data in the client)
  • Full RIM database running on the client
  • Auditing on the mobile client
  • Act/Entity templates and display
You can download from: (CTP 2)

Software Development Kit (SDK)

The OpenIZ SDK allows jurisdictions or independent firms to extend the platform to a variety of use cases. The OpenIZ database is based on a simplified version of the powerful HL7 Reference Information Model. This means that in addition to immunizations, it can be used for general encounter tracking, disease surveillance, general practice, etc.

The software development features the following tooling:
  • An applet compiler for bundling and signing your applets
  • LogViewer which is handy for sifting through large OpenIZ device logs
  • BrainBug which is a windows tool that can interpret Android ab files easily
  • OIZDT which includes tooling for debugging business rules and clinical protocols
  • MiniIms which allows developers to quickly test their applets on a self-hosted IMS in Linux, Windows or MacOS X.
You can download from: (CTP2)

Immunization Management Service (IMS)

The IMS is the main integration point for the OpenIZ solution. It is currently available in binary form for Microsoft Windows operating systems. Unfortunately this CTP doesn't include graphical configuration tools. We are preparing more documentation for the configuration of the IMS which should be available before the Edmonton release ships in September.

The current CTP IMS supports the following features:
  • Base IMSI, RISI, and AMI interfaces which OpenIZ tooling uses to communicate with the IMS
  • Full implementation of the simplified reference information model with versioning support for objects.
  • Base dataset for common materials, codes.
  • Persistence storage plugins for
    • PostgreSQL
    • Microsoft SQL Server (deprecated)
  • Support for fast no-SQL memory caching either in-memory or via REDIS
  • Full import capability from GIIS
  • Server side execution of applet business rules, and clinical protocols
  • Integration with Jasper Reports 6
  • Two factor authentication
    • Email supported via SMTP
    • SMS supported via Twilio
  • Standards based integration (please note these have not been taken to an integration testing event yet):
    • HL7 FHIR STU3 : Patient, Immunization, Immunization Recommendation, Condition, Adverse Event, Allergy Intolerance, Medication Administration, Observation, Substance, and Medication.
    • IHE CSD : Import facilities, villages, and relationships between from a CSD document
    • IHE ATNA : Supports DICOM and RFC-3881 audits. Note that the content of these audits are not standard
    • IHE PIX/PDQv2 & v3 : Supports the broadcasting of new patient registrations to a central EMPI, and can also receive ITI-10 and ITI-8 notifications from a central EMPI.
    • IHE SVS : For importing concept terminologies into the IMS data store
    • GS1 BMS : For order & shipping support.
      • Broadcasts: order, receivingAdvice
      • Receives: orderResposne, despatchAdvice, logisticsInventoryReportRequest
    • OAUTH 2.0 + JWT for authentication
We're currently updating so you can join a working OpenIZ realm.

You can download the CTP here: v.0.9.6 (CTP)

Getting Started with the OpenIZ SDK

Ever wanted to get started developing your own plugins for OpenIZ but don't know how? Well, this handy video on YouTube guides you throu...