OpenMRS FHIR Module - Initial design

*** Warning ***

This page contains initial design plans, and will be retied shortly. For the latest information on module development, please refer to the OpenMRS FHIR Module page.

Introduction

The purpose of this page is to serve as the requirements and design document of the proposed OpenMRS FHIR module.

Deliverables for Phase 01

(A) The scope of phase 01 will be limited to the export of a subset of OpenMRS data as FHIR resources

(B) The development of an OpenMRS FHIR module which supports two types of requests,

Type (A) : When queried for a specific FHIR resource (identified by its UUID),

• will return an appropriate FHIR representation in XML or JSON format
  or
• will return an appropriate FHIR resource object to be re-used by other services within the OpenMRS platform

Examples of such requests are 'return all observations for encounter X' or 'return patient identified by UUID 'X')

Type (B) : When queried for a specific set of Observations restricted by a value set,

• will return a bundle of FHIR observation resources in XML or JSON format
  or
• will return a list of observation resource objects  to be re-used by other services within the OpenMRS platform

Examples of such requests are 'return all CD4 count records for patient identified by UUID 'X'

• Here, CD4 count will be identified via a specific concept mapping, and represent the 'value set' the user requires. We will support value sets with multiple concept mappings, thereby suporting requests with larger scope such as 'get all vital signs (identified by value set X) for patient identified by UUID 'X'

(C) The FHIR resource objects to be supported  during the first phase of this project are,

• Composition
• Encounter
• Patient
• Location
• Observation
• Practitioner

(D) The OpenMRS FHIR module will support (a) the retrieval of data identified by their UUID's and (b) data filtered by a value set of concept mappings. For searching using other parameters such as name, date range etc., we will use the OpenMRS Rest module. Once specific data objects to export have been identified via the Rest module, they will be retrieved via requests to the OpenMRS FHIR module.

(E) The operational unit of work to be completed during this phase is the development is

•  a composition resource (consisting of the aforementioned resource objects) that will be used to model an OpenMRS encounter. The user will be able to export OpenMRS encounters by making a request to obtain the necessary encounter identified by its UUID. In addition, the request will also contain the type of response (XML/JSON/FHIR object) specified in the message header.
• A bundle of FHIR observation resources representing a specific subset of patient observations requested by the user.

(F) The creation of FHIR profiles that represent the resources being exported.

Deliverables overview

• Must haves
  //to be completed
  
  
• Nice to haves
  //to be completed

The OpenMRS FHIR module will support OpenMRS Version x and above

Modeling of FHIR  resources to represent OpenMRS encounters

OpenMRS encounters will be represented in FHIR format using a combination of FHIR resources. 

An architectural digram depicting how FHIR resource objects will be tied together into a composition resource is as follows,

As shown above, each Composition will have a Section that will refer to one or many other sections, each holding a different FHIR observation resource. Top level sections will be used to represent Observation groups.

NOTE: The above image depicts the FHIR representation of a SINGLE OpenMRS encounter

Modeling of FHIR  resources to represent a list of OpenMRS Observations filtered by vital signs

//To-do : insert image

Technical requirements

• The OpenMRS FHIR API module will extend on the OpenMRS Rest module. It will closely align itself to the design of the OpenMRS Rest module, and where possible, re-use features already implemented in this module.
• The module will depend on third party FHIR API's for FHIR message building, marshaling and validation.
• Security features will be provided via the OpenMRS Rest module

Selection of technical frameworks and API's

Following considerable discussions, the HAPI FHIR API was selected to be used for FHIR resource modeling, validation and parsing. Though relatively new, the HAPI FHIR API was selected over the more robust and tried-and-tested FHIR Reference implementation due to long term sustainability concerns.

We will use HAPI FHIR release Version x for the first release of the OpenMRS FHIR module

Design of the OpenMRS FHIR module

The module structure will be broken into two types of classes; FHIR resource classes and corresponding controllers. Each controller will be identified by a specific URL, which will be used to export OpenMRS data.

As an example, an URL such as /ws/rest/v1/fhir/location/{uuid} will be intercepted by the FHIR Location controller, while a URL such as /ws/rest/v1/fhir/patient/{uuid} will be intercepted by the FHIR patient controller. The controller will forward this request to the relevant FHIR resource object, which will obtain the specified object via its UUID, convert it to a representation similar to that prepared by OpenMRS Rest module resources, and return them to the controller, which will be responsible for converting them into FHIR Resource objects, and marshaling them into xml/json for exchange.

The format the FHIR resource must be returned in (xml / json or as a FHIR object) will be defined via the HTTP accept header in the GET request sent to the controller.

The design we propose here mimics the pattern used to generate and export HL7 V2 messages from the OpenMRS Rest module.

The resource object will be responsible for,

• Obtaining OpenMRS objects based on the specified UUID
• Converting said OpenMRS objects into an FHIR representation
• forwarding said FHIR representation to the relevant controller
  
  Ideally, each FHIR resource class will extend the resource classes introduced in the OpenMRS Rest module, and re-use some of the methods defined therein (etc. getByUniqueId(UUID).
  
  

The controller object will be responsible for,

• Transforming the FHIR representation into an FHIR object via a custom marshaller, and then return it in either xml / json format, or as a FHIR object itself to be used by any services internal to the OpenMRS platform

Questions

(a) What about instances where multiple FHIR resources need to be compiled together (etc. the Composition resource) ?

In such an event, the request url will point to the FHIRCompositionController, which is aware of what resources are needed to build a composition object, and can assemble them together. The FHIRCompositionController will call the appropriate controllers, obtain the FHIR objects from them, and use them to build the composition resource, which will be returned to the user in the message format they requested.

(b) How will we marshal FHIR resources into XML or JSON ?

Ideally, we will register new handlers to the FHIR module which, instead of using the traditional xml parsers used by the OpenMRS Rest module, will use features in the HAPI FHIR module to marshal FHIR resources. This will include some research, and possibly the need to override marshalers previously registered by the Rest module.

Work flow for exporting an encounter identified by its UUID

Step 01: User makes a request for an encounter identified by its UUID

Step 02: The FHIRCompositionController intercepts the request, and calls the relevant controllers necessary to build the FHIR composition resource

Step 03: Each secondary controller returns a valid FHIR object to the FHIRCompositionController

Step 04: FHIRCompositionController builds the complete FHIR resource, and transforms it to the export type (XML/JSON or FHIR object) as per the users preferences

Step 05: The FHIR Composition resource is returned to the user

Note : The FHIR Composition resource will contain URI's to other FHIR resources included in the composition. To obtain these, the user must make additional requests specifically requesting these resources.

The secondary requests will be intercepted by the specific resource controllers, which will return the full representation of the appropriate FHIR resource to users.

Work flow for exporting a list of observations, filtered by value sets