OpenMRS HL7Query Module Design Page

Overview

The aim of this project is to allow users to download OpenMRS data (encounters) as hl7 objects.
Initially, we will support only the export of encounters as ORUR01 objects.

1. Users will be able to request to download either a single encounter or multiple encounters as a single ORUR01 message
   • Something like /openmrs/hl7query/orur01?patient=uuidofpatient&encounter=uuidofencounter
2. The ORUR01 message will contain the elements MSH, PV1, PID, OBR and OBX
3. The PV1 and PID segments (and then the OBR/OBX) will repeat for each extra encounter included
4. The hl7 message will be exported as a pipe delimited object
5. The admin can define the exact elements, layout and flow of each different message type by creating groovy templates
   • Groovy template is xml based
   • The xml refers to exact fields in hl7
   • HAPI is used to parse the xml into hl7

Create the message

An ORUR01 message consists of several segments (MSH, PID, PVI, OBR, OBX)
We have created several default groovy templates to create each of these message segments. The main "orur01" template is responsible for joining them together to output the final (and complete) ORUR01 message.

The groovy template would essentially be this: (this is PSEUDO CODE and obviously not actual groovy)

createORUR01Message(patient, encounterList) {
     getMSHTemplate(patient);
     Loop over list of encounters
         getPIDTemplateOutput(patient);
         getPV1TemplateOutput(patient, encounter);
       Loop over list of obs in current encounter {
            if obs group
               getOBRTemplateOutput(obs);
            else if not obs group
               getOBXTemplateOutput(obs);
       }
    }
}

The admin can edit the orur01 main template above and call different templates or hard code more values.

The admin could also open the "PID" or "MSH" template and edit there (which would effect every other template calling the PID or MSH template)

Tickets, etc

Sprint wiki page: https://wiki.openmrs.org/display/RES/Export+of+HL7+Messages+Sprint
Jira dashboard for sprint: https://tickets.openmrs.org/secure/Dashboard.jspa?selectPageId=12052
All tickets for this module: https://tickets.openmrs.org/browse/HLQRY

Use case scenarios

Scenario 1: User requests hl7 message for patient X and encounter Y

1. Admin installs the hl7query module
2. Admin does not make any changes to the default configuration (He does not change the settings (formerly global property 1.8 and below) identifying the selected ORUR01 message template to export, and nor does he attempt to edit any templates / segments)
3A. User makes a valid request to the hl7query controller class passing in the uuid of the patient and uuid of the encounter
The controller retrieves the "orur01" groovy template.
The template rendered uses the given patient+encounter and turns the template into hl7-like xml (see A Developer's Guide to the ORUR01 Message)
The xml is passed through HAPI to turn the xml into hl7
Details of the user's request are logged.
3B. User makes an invalid request to the hl7query controller class.
The user receives an ACK message notifying him of the error.
Details of the users request are logged.

Scenario 2: Admin wishes to change the default template.

1. Admin installs the hl7query module
2. Admin navigates to the module administration page
3. Admin wishes to create a custom ORUR01 template

Scenario 3: Admin wishes to edit part of the default template.

1. Admin installs the hl7query module
2. Admin navigates to the module administration page
3. Admin clicks on the template link. This leads him to an editable text area where he can edit and save the template. Changing which templates are called and/or adding in more xml hl7 elements.