Case Study: FHIR2 Module Implementation Guide
Organization or Project: 2022 Google Season of Docs
Organization Description:
OpenMRS stands for Open Medical Record System. It is an open-source, robust software developed to manage patient clinical data. The OpenMRS platform and reference application are supported by a diverse community that comprises government representatives, implementing partners, and volunteers. A recognized Global Good, OpenMRS is currently used to manage more than 15.8 million patients at over 6,500 health facilities in 40+ countries.
Authors: Jennifer Antilla Christine Gichuki Sharif Magembe Namanya Abert
Problem Statement
The OpenMRS community developed and maintained a FHIR2 module to support standards-based data exchange. As with all other OpenMRS products, the FHIR2 module is freely available and ready for use. Multiple queries came up on the community’s interactive platform, Talk, in which a developer choosing to use FHIR resources spent considerable time waiting for assistance or sources for information. Additionally, few community members were aware of how to implement a FHIR resource correctly. For easy use and to address these obstacles, there was clearly a need for a FHIR Implementation Guide (IG) to guide developers and newcomers.
Proposal Abstract
By developing a FHIR Implementation Guide (IG) for the OpenMRS FHIR2 module in the format set out by the FHIR community, the OpenMRS community provides OpenMRS developers and implementers with easy-to-use and testable technical guidance for implementing the OpenMRS HL7 FHIR resources.
Here is a link to the technical proposal.
https://talk.openmrs.org/t/mapping-of-immunizationrecommendation-resource/34826
https://talk.openmrs.org/t/500-error-cant-post-patient-into-openmrs/35540
Project Description
Creating the proposal
The OpenMRS community has participated in the Google Summer of Code and Google Season of Docs since their inception. For Google Season of Docs, the community’s Documentation Team followed several tried and true practices for engaging the community during the proposal development phase. Kaylin Bracey, a community technical writer, shared a Talk post soliciting ideas from the community on potential ideas for technical writing projects and Community Director Jennifer Antilla approached community squads to raise awareness of this opportunity. The FHIR squad shared their proposal idea on the Talk thread about enhancing documentation around the FHIR2 module. They originally considered proposing this project for Google Summer of Code 2022 and recognized that it was a better fit for Google Season of Docs.
This was then followed by drafting the actual proposal, which was an open and collaborative effort involving key community members, such as Piotr Mankowski (FHIR Squad, University of Washington) and Jennifer Antilla (Strategy & Operations Team, OpenMRS).
Budget
Since this was our second experience with Google Season of Docs, we looked at our previous experience to see what worked well and determine what we might want to change. Growing our community’s talent remains a priority, so we decided to continue with a fellowship model that included monthly stipend payments to two technical writers.
We also budgeted in time for community management support, anticipating that the technical writers would benefit from support raising the visibility of their work through various community channels, connecting them with key subject matter experts for feedback, and creating presentations and videos to showcase their project at virtual community meetings.
In retrospect, our budget was slightly under budget.
Participants
The core team working on the project was:
- Technical writers: Namanya Abert, Sharif Magembe
- Mentors: Moses Mutesasira, Piotr Mankowski
In sourcing for the technical writers, a call was posted to the community channel in which a number of applications applied. Following a vetting process that included open, community interviews, Namanya and Sharif were selected as technical writers to support the project.
Namanya and Sharif worked alongside Moses and Piotr: Moses and Piotr laid the groundwork for the project skeleton, The team had weekly calls every Tuesday where they met and discussed the development progress. Piotr shared a wealth of resources that helped Namanya and Sharif gain expertise in writing FHIR IGs.
In developing the IGs, Sharif and Namanya collaborated with Jose Costa, a well-known and respected FHIR expert in the Global Goods community, who developed the OpenHIE implementation guide. They also did research by reviewing other existing FHIR IGs that have been developed from sources, such as FSH finder.
Timeline
The planned timeline was as follows:
- June 1, 2022 - June 17, 2022: Activity 1.1: Research tools and best practices for writing a FHIR IG
- June 20, 2022 - July 1, 2022: Activity 1.2: Use FHIR shorthand and compile it using Sushi
- July 4, 2022 - September 30, 2022: Activity 1.3: Write FHIR-based specifications as part of the FHIR2 Module IG
- October 3, 2022 - October 14, 2022: Objective 2: Evaluate the FHIR2 module IG process
- October 17, 2022 - October 21, 2022: Activity 2.1: Gather feedback on the FHIR IG and creation process
- October 24, 2022 - October 28, 2022: Activity 2.2: Make recommendations on improvements and future contributions to the IG
October 31, 2022 - November 30, 2022: Activity 2.3: Disseminate the FHIR2 Module IG, lessons learned writing postman testables using test scripts, and recommendations through community showcases and videos
Results
The list below displays the IGs developed during the period:
- OpenMRS Encounter Resource
- Openmrs Patient Resource
- Openmrs Person Resource
- Openmrs Observation Resource
- Openmrs Condition Resource
- Openmrs Location Resource
- Openmrs AllergyIntorelance Resource
- Openmrs Diagnostic Resource
- Openmrs Service Request Resource
- Openmrs Address Resource
- Examples of Testables created include
- Get FHIR Capability Statements using Postman testing.
- CreateFHIR Test Patient in Postman
- Delete Patient
- Update Patient
Metrics
We initially proposed three metrics:
- OpenMRS FHIR2 Module IG published
- OpenMRS FHIR2 Module IG demonstrated to the community in at least one community meeting or community mini-meeting
- # of OpenMRS implementations are aware of the FHIR2 Module IG
We have met all of these metrics to a degree: the FHIR2 module IG is published, we have demonstrated the IG at several community squad meetings, and at least two OpenMRS implementations are aware of the IG.
However, the coming months offer opportunities to do better and demonstrate this work to the broader OpenMRS community and OpenMRS implementations, including the upcoming OpenMRS Implementers Meeting.
Analysis
What went well?
Working with OpenMRS developers like Piotr and Mozzy meant we acquired significant experience around FHIR HL7 standards, from documenting and testing the resources to how these resources communicate with other FHIR servers from and to the OpenMRS FHIR module.
What was unexpected? What hurdles or setbacks did you face?
We did not expect that the Implementation Guide template would pick directly from the FHIR HL7 servers. One improvement that needs to be considered in the future is how to make the complete customisation of the Implementation Guide template easier. Through this project, we customised everything using Sushi, which is easy for technical writers to use.
At times, it was challenging to get feedback from community members who might benefit from this new documentation. We’ll need to continue to demo and promote the new FHIR IGs at various community events.
Do you consider your project successful? Why or why not?
Yes! This documentation will be a great resource for OpenMRS developers who want to implement OpenMRS FHIR-supported resources. No more worrying about the structure of the resource payload since this has been documented in the resource examples!
Summary
Before this year’s Google Season of Docs, our FHIR resources were documented in spreadsheets and on random OpenMRS FHIR Squad wiki pages. OpenMRS implementers who wanted to use FHIR resources couldn’t find what they were looking for easily and any gaps in FHIR resources were obscured.
Sharif and Namanya’s work on a collection of testable FHIR IGs for our FHIR2 module means that our FHIR resources are better organized, easier to find, and use. We also have a growing number of community members who have the know-how to expand on this collection.
Appendix
Text of original proposal:
2022 OpenMRS Google Season of Docs Proposal
Implementation Guide GitHub repository and IG Link:
https://github.com/openmrs/openmrs-contrib-fhir2-ig
Showcasing Implementation Guide: https://www.youtube.com/watch?v=OJxa3Sx5Yg8