...
The aim of this project is to allow users to download export OpenMRS data (encounters) as hl7 objects.
Initially, we will support only the export of encounters as ORUR01 objects.
- 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
- The ORUR01 message will contain the elements MSH, PV1, PID, OBR and OBX
- The PV1 and PID segments (and then the OBR/OBX) will repeat for each extra encounter included
- The hl7 message will be exported as a pipe delimited object
- 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
Documentation / How-To
For now, see OpenMRS HL7Query Module Design Page
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)
| Code Block |
|---|
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)
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 global property 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.
Downloads
http://modules.openmrs.org/modules/view.jsp?module=It is built using Groovy templates, and can be extended / configured by users as per their wishes.
This document will cover the following information -
- What types of messages are currently supported by the hl7query module
- How may users extend on the hl7query module
- An introduction to the hl7query segments currently used in the module
- A technical overview of how the module is built
- Installation and configuration of the hl7query module
- Making requests
What types of messages are currently supported by the hl7query module?
The default version of the hl7query module supports only the export of ORUR01 messages.
This means that the first release of the module contains only hl7 templates that support only the generation of ORUR01 message segments. However, developers are free to write up their own custom hl7 message templates, which can be added to the module. Custom templates can be used to export OpenMRS data in any form of hl7 message.
How may users extend on the hl7query module?
Users may extend upon the default version of the hl7query module by adding custom hl7 templates of their own. This may be done via the 'Manage Templates' page.
However, this requires a strong knowledge of groovyscript.
Adding a new template can be done as follows -
1) Creating a new template from scratch
2) Editing an existing template
If a user wishes to edit an existing template, simply click on an existing template, edit it, and save as new.
To create a new template navigate to the 'Manage Templates' page, and add the new template
Understanding the 'Manage templates' Page
Following is an explanation of what each segment of the 'Manage templates' Page represents.
Template name : The name by whih the template will be identified. Examples : Generic PV1, FullPV1 or AMPATHPV1
Entity : The hl7 segment which the template represents. Examples : PV1, MSH, OBR
Language : The language the templaate is written in. Currently, this may be only Groovyscript
Template : The actual Groovyscript code.
A Groovyscript template may also refer to another existing template by name.
Note: If the new template represents an combined hl7 message type (ORUR01, ADT etc.), and the use wishes to export data in that particular message type, then he / she must also edit the 'Template' global property to point to the given template.
Making Requests
The hl7query module supports only GET requests. All GET requests are made on the HL7QueryController.java class.
A GET request can consist of the following optional parameters-
- patientId (The patient identifier number we are using)
- idTypeUuid (The UUID of the patient identifier we are using)
- encounterUuid (a UUID of the encounter which we want to retrieve)
- startDate (Start date to filter retrieved encounters)
- endDate (End date to filter retrieved encounters)
A sample GET request would look as folllows -
/openmrs/module/hl7query/ORUR01.htm?patientId=100&idTypeUuid=8d79403a-c2cc-11de-8d13-0010c6dffd0f
The above request contains the patient id and the UUID of the identifier type. Other additional url parameters (specified above) can also be added to the URL as per the users wishes.
Note: please set an Implementation ID on OpenMRS for this requests to work.
Potential Improvements
Users may document potential improvements / fixes to the module in the following document -
Downloads
https://addons.openmrs.org/#/show/org.openmrs.module.hl7query
Source code: https://github.com/OpenMRS/openmrs-module-hl7query
...