GSoC 2023 - Add Support for FHIR PATCH operations - Final Presentation

mherman22 · August 26, 2023, 9:49am

Add Support for FHIR PATCH operations

Project Title: Add Support for FHIR PATCH operations
Primary mentor: Ian Bacher @ibacher
Backup mentor: Abert Namanya @abertnamanya
Project Link: GSoC-2023: FHIR: Add Support for FHIR PATCH operations
Project Report: GitHub - mherman22/GSOC-FinalReport

Overview

OpenMRS is using the FHIR API more and more in place of the REST API. However, the FHIR API is, by default, quite verbose. Supporting PATCH operations would allow us to support partial updates to FHIR resources without needing to send the whole resource from the client to the server.

The journey of enhancing OpenMRS through the addition of support for FHIR Patch Operations has been a remarkable experience. In light of the growing importance of the FHIR API as a replacement for the REST API, this project sought to introduce PATCH operations to enable more efficient partial updates to FHIR resources. This feature empowers users to modify specific elements within resources without the need to transmit entire resources between the client and the server.

In the context of the HAPI FHIR library, “patching” refers to the process of making partial updates to a FHIR (Fast Healthcare Interoperability Resources) resource. FHIR resources are representations of healthcare-related data, such as patient, observations, medications, etc., designed to be easily shared and exchanged between different healthcare systems.

Patching allows you to modify specific parts of a FHIR resource without having to replace the entire resource. This can be particularly useful when you want to make minor updates or corrections to a resource without sending the entire payload over the network. The PATCH operation follows the HTTP PATCH method semantics and is designed to be more efficient than the PUT or POST methods for updating resources, especially when dealing with large resources or slow network connections.

The Patch operations used within the above mentioned patch formats are add, replace, move, copy, test, remove .

Format for supporting a single patch

Detect the incoming format(either json-merge patch, json-patch or xml-patch)
Load the existing resource in the appropriate format
Apply the patch

Objectives:

Implement JSON PATCH operations on all OpenMRS FHIR R4 resources and ensure to have the tests working perfectly. - COMPLETED
Implement JSON MERGE PATCH operations on all OpenMRS FHIR R4 resources and ensure to have the tests working perfectly. - COMPLETED
Implement XML PATCH operations on all OpenMRS FHIR R4 resources and ensure to have the tests working perfectly. - COMPLETED

Contributions:

During the project, I worked on various code repositories and pull requests to bring the functionality of PATCH operations to the FHIR API:

Repositories:

Pull Requests:

Found Issues:

Medication Dispense was not added to the landing page of the FhirIG
Medication was not added to the landing page of the FhirIG

Fixed Issues:

Other related work:

During this GSoC jouney, i was able to do other work on the FHIR module as assigned by my mentor and below are the pull requests;-

Talk Thread links:

Jira Epic

[FM2-573] Add support for FHIR PATCH operations - OpenMRS Issues

Weekly Blog Posts:

Throughout the development cycle, I chronicled my progress and insights through weekly blog posts:

Video(Demo)

Resources:

Future Works:

While significant strides have been made, certain aspects require further attention. Completing the integration of PATCH operations with complex FHIR resources(ServiceRequest) is a priority. Additionally, refining error handling and optimizing performance will ensure a robust implementation.

Part of the work to be worked on includes but not limited to the following;-

Ensure Service Request resource is fully translated
Ensure Service Request resource supports all the PATCHing formats implemented above.
Write more tests in regard to the how the json documents and xml documents should be written in the attempt to give clearer error messages.(To Be Discussed)
We could also implement the PATCH operations for the R3 resources(To Be Discussed).

Thoughts on GSoC:

Participating in GSoC 2023 on the OpenMRS platform has been an enlightening journey. Working with esteemed mentors like Ian Bacher and Abert Namanya has been instrumental in my growth. I have gained insights into the world of healthcare informatics, API optimization, and collaborative open-source development. Looking forward, GSoC has paved the way for a continued commitment to enhancing healthcare technology. My knowledge in FHIR standards and OpenMRS data model and how the two integrate to complement each other has greatly grown.

A special thanks to GSoC, OpenMRS, mentors, and the vibrant community for making this journey a resounding success!

cc: @kdaud @jayasanka @grace @jennifer @janflowers @erica @ibacher @dkayiwa @mozzy @samuel34 @jnsereko @jwnasambu @abertnamanya @pmanko @reagan

wodpachua · August 26, 2023, 9:52pm

Godspeed on the journey forward writing code to save lives

grace · August 31, 2023, 3:51am

Thanks so much @mherman22 for this very well written post. The demo video was especially helpful for me to visualize

FYI @mseaton and @mogoodrich I imagine this PATCH operation flow might be rather useful for the Retrospective Data Entry/Editing work you have on the roadmap

One small question out of curiosity from the demo - when the birthdate is changed from “1996”, you entered 2023, but it turns into “2023-01”. How does OMRS decide (or rather where is that configured) to default to January if the month is not known?

mherman22 · August 31, 2023, 9:25am

This is handled at https://github.com/openmrs/openmrs-module-fhir2/blob/6dc997ced929e319d08857df81edd3c465ae5a07/api/src/main/java/org/openmrs/module/fhir2/api/translators/impl/BirthDateTranslatorImpl.java#L43-L49

here’s the code:

			// 5 years is the cut-off for WHO and CDC infant growth charts, so it seems like a convenient break between
			// "infant" and "child"
			if (Period.between(birthDate, now).getYears() > 5) {
				dateType.setValue(person.getBirthdate(), TemporalPrecisionEnum.YEAR);
			} else {
				dateType.setValue(person.getBirthdate(), TemporalPrecisionEnum.MONTH);
			}

To shed more light,

If the calculated age is greater than 5 years, the DateType is set with the precision YEAR. This means that only the year component of the birthdate will be used, and the rest of the components (month, day, time) will be ignored. i.e 1996
If the calculated age is 5 years or less, the DateType is set with the precision MONTH. This means that both the year and month components of the birthdate will be used, and the day and time components will be ignored. i.e 2023-01
Since the precision is set to MONTH, the day component defaults to the first day of the month (January 1st), and the month component remains the same (January). Therefore, when you provide a birthdate of 2023(like i did in the video), the result is 2023-01, indicating the year and month of the birthdate while disregarding the specific day and time.
If you were to provide a birthdate of, say, January 15, 2023, the result would still be 2023-01, as the precision is set to MONTH, and the code-snippet above doesn’t consider the day component beyond the month of January.

Note: This precision distinction aligns with the levels of precision defined in the TemporalPrecisionEnum enum class. The YEAR precision corresponds to years, and the MONTH precision corresponds to months.

probably @ibacher could correct me i’m wrong

jonathan · August 31, 2023, 10:12am

great work @mherman22

ibacher · August 31, 2023, 3:25pm

This is exactly right. This is configurable in the sense that an implementation is free to override that translator with any translator that implements the same interface but returns a different date. (The FHIR2 module is basically designed so that almost all implementation details can be swapped out by other modules).

The default rule is based on the fact that international guidelines tend to be written in terms of months for ages <= 60 months and years beyond that. Intuitively, the idea being captured here is that the difference between an estimated age of “50 years” and an estimated age of “50 years and 5 months” is unlikely to be clinically relevant, but the difference between an estimated age of “33 months” and an estimate age of “38 months” is more likely to be clinically relevant.