GSoC 2020 - Add support for FHIR Narratives - Final Presentation

Project Title Add support for FHIR Narratives
Primary Mentor @herbert24
Backup Mentors @ibacher @suthagar23
Student @iamsr
Project Link Wiki Page Link


FHIR (or Fast Healthcare Interoperability Resources ) is a standard for exchanging electronic health records. It describes elements (called resources ) and an API (or application programming interface ) for implementation of the same. FHIR Narratives are human-readable representations of resources, in the form of XHTML fragments. The project aims at adding support for FHIR Narratives to the FHIR2 Module of OpenMRS .

As a part of this project, we have successfully implemented support for FHIR narratives, along with addition of other useful features like localisation of narratives and custom narrative support.


Following were the objectives of the project:

  • Create FHIR narratives for all resources defined by OpenMRS FHIR module (COMPLETED)
  • Develop a framework to support implementation-driven overrides for FHIR narratives (COMPLETED)
  • Add support for localization of the generated narratives (COMPLETED)

Brief Implementation Details:

Our implementation uses Thymeleaf Template Engine for rendering of narratives. The narrative templates are basically XHTML fragments using Thymeleaf Standard Dialect. The narrative basically gets associated to the resource as the text element. The implementer can then use it in the desired way, using the getText() method.

Narrative templates for all the supported resources: AllergyIntolerance , Condition , DiagnosticReport , Encounter , Location , Medication , MedicationRequest , Observation , Patient , Person , Practitioner , RelatedPerson , ServiceRequest , Task were created. Also, narrative template for the PractitionerRole resource was created, considering its future scope of addition.

Support for narrative override or custom narratives was added through an option of specifying a global property narrativesOverridePropertyFile for custom property file location which would contain locations of narrative overrides for specific resources. Since it is a global property, no changes are required in the code of FHIR Module for adding custom narratives.

The localisation support was added by implementing OpenmrsMessageResolver and using it to populate the narratives with localised text through keys stored in message files ( messages_*.properties ).

Here is an example of how a narrative looks like:

Example used for the above narrative:


All contributions during this project were done in the OpenMRS FHIR2 Module, the details of which are given below:

GitHub repository:

Public Talk thread for project related discussions:

Issues and Pull Requests:

Note: The issue number (eg. FM2–193) contains link to the issues and PR number (eg. PR#194) contains link to the pull requests.

  • FM2–193 : Generate default narratives provided by HAPI FHIR
    Status: FIXED
    Pull Requests: PR#194 [ MERGED ]
  • FM2–194 : Create default narratives for resources (AllergyIntolerance, MedicationRequest, Condition)
    Status: FIXED
    Pull Request: PR#198 [ MERGED ]
  • FM2–207 : Create default narratives for resources (Encounter, Observation, Location)
    Status: FIXED
    Pull Request: PR#207 [ MERGED ]
  • FM2–208 : Create default narratives for resources (Person, Practitioner, ServiceRequest)
    Status: FIXED
    Pull Request: PR#219 [ MERGED ]
  • FM2–230 : Create default narratives for resources (RelatedPerson, Task, PractitionerRole)
    Status: FIXED
    Pull Request: PR#232 [ MERGED ]
  • FM2–243 : Fhir2 build errors in windows environment
    Status: FIXED
    Pull Request: PR#279 [ MERGED ]
  • FM2–249 : Improve content and layout of narratives
    Status: FIXED
    Pull Request: PR#238 [ MERGED ]
  • FM2–251 : Add support for overriding default narratives
    Status: FIXED
    Pull Request: PR#257 [ MERGED ]
  • FM2–252 : Add support for relative path with prefix β€˜openmrs:’ for narrative templates
    Status: FIXED
    Pull Request: PR#255 [ MERGED ]
  • FM2–280 : Add support for localisation of narratives
    Status: FIXED
    Pull Request: PR#278 [ MERGED ]
  • FM2–281 : Add checks for empty properties in narrative templates
    Status: FIXED
    Pull Request: PR#273 [ MERGED ]
  • FM2–295 : Narrative generation failing for MedicationRequest resource
    Status: FIXED
    Pull Requests: PR#275 [ MERGED ], PR#288 [ MERGED ]
  • FM2–297 : Create default narratives for resources (DiagnosticReport, Medication, Patient)
    Status: FIXED
    Pull Request: PR#287 [ MERGED ]
  • FM2–299 : Add necessary Javadoc to methods and classes
    Status: IN PROGRESS
    Pull Request: PR#291 [ OPEN ]

Weekly Blog Posts:

Following are links to all the blogposts describing my weekly progress throughout the GSoC Coding Phase:

Here is a GitHub Gist which is a minified compilation of all the Reports: Gist Link


Following are some of the resources for reference:

Future Works:

  • An additional planned task for the project was implementation of search feature for FHIR resources using _text parameter . This would be one of the future tasks related to this project.
  • Another nice addition could be implementation of a web-based client for viewing the FHIR narratives of resources .

Project Overview and Demo:

Thoughts on GSoC:

My experience in working on this GSoC’20 project with OpenMRS was simply awesome. It was one of the best experiences I’ve ever had. Not only I got a chance of contributing to such a big real-world project, but also I got to learn a lot throughout the program.

I would really like to thank @ibacher who always supported me and guided me through the project and helped me a lot in resolving the blockers I faced. I would also like to thank @herbert24 and @suthagar23 who also mentored me and were always there for support throughout the project.

Also, I would like to thank the entire OpenMRS community which has always been so supportive. Be it solving issues, suggesting improvements or even finding issues with the implementation, the OpenMRS community has always been there for help. I would definitely say that it is one of the most active and supportive opensource communities, and that I take pride in being its member.

Finally, I would thank Google for conducting GSoC and providing this great opportunity for working in such a great opensource community on such a big, real-world project.

1 Like