OpenMRS Implementation Guide (FHIR & RESTful)

Development
1

Hello,

I am creating a integrated system having OpenMRS for storing patient clinical records and utilise the functionality of OpenMRS FHIR Complience. My aim was to build a system which is FHIR, HIPPA Compliance.

I am using FastAPI (Python) application to intract with the OpenMRS infrastructure as there is a need of some AI related work in my system.

I was stucked in getting the workflow of the whole OpenMRS system to get my job done with all the compliances checks.

Unable to find the exact documentation regarding the payloads of endpoints while accessing it through Postman.

Using modules: a) OpenMRS Core b) OpenMRS REST c) OpenMRS FHIR2

I need it to be fully complianced with FHIR

2

We have a FHIR implementation guide Table of Contents - OpenMRS Core FHIR Implementation Guide v0.1.0

As for the rest api, we have https://rest.openmrs.org#openmrs-rest-api

Hope those help

3

Is OpenMRS not fully complianced with the FHIR Standard. As i am following a Standard Hospital Management Scenerio where multiple roles maintain all kinds of patient records and medication histories (precriptions and consultancies). Along with Robust Role Based Access throughout ?

Do we need to move in Hybrid mode (FHIR + Rest) or FHIR Provide that support ?

Through, Rest Docs, I got the flow of

Person > User/Patient/Medical Staffs > Patient Visits > Encounters > Observations and move further with it ?

Will all these provided in FHIR ?

4

If you want to benefit from some functionalities like RBAC then hybrid is the way to go. Follow this thread for more insights →

Some of these have been translated to a point that benefits the community But the advantage is the fhir2 module is extensible hence you should be able to build on top of the existing functionality.

5

As I was exploring the functionalities of the OpenMRS FHIR and REST modules, I noticed that the term “Concept” in the REST module provides flexibility for storing more tailored information. However, this functionality seems to be unavailable in the FHIR module.

My concern is:

If I primarily use the FHIR module for all RESTful interactions but complement it with certain functionalities from the OpenMRS REST module (such as “Concepts”), would this break the standard compliance rules for being a FHIR-compliant application?

If it does violate compliance, what steps should we take to ensure full FHIR compliance while still maintaining the required flexibility?

6

The OpenMRS FHIR Module does not (yet!) cover all possible FHIR resources nor all the data in OpenMRS, but we have aimed to cover the highest priority items. We have been building out the module with community implementers based on their pressing needs. As copied from the docx.

In addition to my previous comment, these are ongoing efforts so feel free to begin discussions on which resources not yet translated into FHIR do you want translated to fully support your usecase.

As for concepts, they have been translated as can be seen at openmrs-module-fhir2/api/src/main/java/org/openmrs/module/fhir2/api/translators/impl/ConceptTranslatorImpl.java at 3432289ddbb143f0828d3d7b81f9060b5e232767 · openmrs/openmrs-module-fhir2 · GitHub

@ibacher @dkayiwa thoughts?

7

This gets into some complicated things. FHIR supports the use of medical terminologies in numerous places using features like Coding, code, CodeableConcept, and the not-yet implemented CodeableReference. In appropriate places, the FHIR2 module will translate between data represented using concepts and the appropriate FHIR representation. This allows ingestion of coded data (where OpenMRS knows about the code system the code comes from). Note, though, that there is no way to create new concepts using the FHIR API. That’s not an operation supported by FHIR at all.

What FHIR doesn’t have is an API for access specific data about an individual concept, instead representing them through either Code Systems or ValueSets. The FHIR2 API gives read-only versions of ValueSets, but it doesn’t support the code system resource.

would this break the standard compliance rules for being a FHIR-compliant application?

There are no hard and fast rules about what “breaks standard compliance” in this sense. It really depends on what your goals are.

8

I hope you are doing well.

I am currently working on integrating and storing various types of patient clinical data (such as medications, check-ups, diagnoses, lab results, and other medical records) within OpenMRS using the FHIR2 module. I would like to understand the complete data flow and best practices for storing and retrieving this information while ensuring interoperability with other healthcare systems.

Could you please provide:

  1. A detailed workflow for storing and managing all types of patient clinical data using OpenMRS?
  2. An overview of how these data types are mapped to FHIR2 resources in the OpenMRS FHIR2 module.
  3. A step-by-step guide on how these records flow within OpenMRS and how they can be accessed via FHIR2 APIs.
  4. Best practices for ensuring consistency, validation, and interoperability when storing clinical data.
  5. Any updated documentation or example implementations that illustrate the storage and retrieval of clinical data using FHIR2.
  6. Description of database schema as per the fhir2 module.

This information will be highly valuable in designing a robust solution that ensures seamless data exchange and adherence to FHIR standards. I appreciate your time and guidance on this matter.

Looking forward to your response on all of these matters in details.

@ibacher @mherman22 @dkayiwa

9

A lot of this is covered in our Implementation Guide, the Wiki, and the base FHIR documentation. Please review our existing documentation. You’ll definitely find some gaps, and we welcome contributions that help build things out for the next person.

1 Like
10

I have reviewed the implementation guide, but since the module is not fully implemented, I am struggling to determine what has been implemented and what has not. The documentation is vast, making it difficult to navigate.

As a result, I am facing challenges in smoothly coordinating within the FHIR2 module. Specifically, I need clarity on which endpoint is responsible for handling which type of data.

Could you please provide a simplified explanation of the following FHIR endpoints and their respective data handling?

  • Condition
  • Group
  • Task
  • Immunization
  • MedicationRequest
  • MedicationDispense
  • Patient
  • DiagnosticReport
  • RelatedPerson
  • ServiceRequest
  • Practitioner
  • AllergyIntolerance
  • EpisodeOfCare
  • Medication
  • Observation
  • Encounter
  • ValueSet
  • Person
  • OperationDefinition
  • Location

Additionally, I would appreciate a clear and structured flow on how to record all data in compliance with FHIR standards.

Thank you!

@ibacher @mherman22 @dkayiwa

11

Those are all standard FHIR endpoints that respond to the standard FHIR REST operations that are documented in the FHIR server’s capability statement. The purpose of the Implementation Guide is to cover the “dialect” of FHIR that OpenMRS speaks. Please review HL7’s documentation on the RESTful API and the descriptions of the various resources.

since the module is not fully implemented

I don’t know what you mean by that. The module is pretty feature-complete, though, as an open source project, we do accept contributions for things that are lacking.

12

I want to know what that means in terms of covering aspect of integration of OpenMRS ?

Another Concern is that:

I have already created Patient and Practitioner records for the hospital. Now, suppose a patient arrives with a complaint of Kidney Dysfunction. Can you provide a workflow of FHIR APIs for managing the complete treatment process using the OpenMRS FHIR Module?

I need an example of how the hospital authority would interact with OpenMRS through APIs, covering the entire treatment process from diagnosis to follow-up.

@ibacher @ibacher @dkayiwa

13

@ibacher Please reply if possible

14

Pretty much that the FHIR module may need additions to support some types of data, but it aligns with many data exchange patterns.

Can you provide a workflow of FHIR APIs for managing the complete treatment process using the OpenMRS FHIR Module?

I don’t think this is a reasonable request. It’s extremely workflow-dependent, which is, itself, extremely dependent both on whatever app you’re integrating with OpenMRS and your OpenMRS implementations configuration. It’s up to you to figure out what those workflows look like and what parts of the FHIR module might be relevant.

At a basic level, you can register a patient through the Patient API, with caveats that OpenMRS Patient Identifiers are necessarily fully supported in that way. I don’t know that we support creating OpenMRS Provider’s from practitioner records, because of how this is internally structured in OpenMRS. The rest very much depends on how you’re collecting data and where it needs to feed to. Most clinical data in OpenMRS will largely be represented as Encounters and Observations, which may require processing from how the data is stored in another FHIR-compliant system.

FHIR only really provides syntatic interoperability. Semantic interoperability results from data flows you design (and hopefully create an Implementation Guide to explain how it works).

A better way to look at it is that the FHIR2 module is a backbone for FHIR support in OpenMRS, but it won’t implement workflows for you and those workflows may need additional capabilities added to your OpenMRS instance. The FHIR2 module is built to be extensible in that way.

15

I have implemented the workflow as per my need. But i am stucked at updating records of patient using Patch Request.

Issues:

  1. In Patient endpoint, Updating rest of the records but not updating the address part. How can i update the specific address using PATCH request.

PATCH: http://localhost:8080/openmrs/ws/fhir2/R4/Practitioner/4bcdc9b3-1157-4966-96f1-6b315aa1a20c

Payload:

[
  {
    "op": "replace",
    "path": "/address/0/city",
    "value": "New City"
  },
  {
    "op": "replace",
    "path": "/address/0/state",
    "value": "CA"
  },
  {
    "op": "replace",
    "path": "/address/0/postalCode",
    "value": "458562"
  },
  {
    "op": "replace",
    "path": "/address/0/country",
    "value": "USA"
  },
  {
    "op": "replace",
    "path": "/gender",
    "value": "male"
  },
  {
    "op": "replace",
    "path": "/birthDate",
    "value": "1985-06-15"
  }
]

Response:

{"resourceType":"Practitioner","id":"4bcdc9b3-1157-4966-96f1-6b315aa1a20c","meta":{"versionId":"1743002100000","lastUpdated":"2025-03-26T20:45:00.000+05:30"},"text":{"status":"generated","div":"<div xmlns=\"http://www.w3.org/1999/xhtml\"><table class=\"hapiPropertyTable\"><tbody><tr><td>Id:</td><td>4bcdc9b3-1157-4966-96f1-6b315aa1a20c</td></tr><tr><td>Identifier:</td><td><div>111aaabbc122334</div></td></tr><tr><td>Active:</td><td>true</td></tr><tr><td>Name:</td><td> Donald <b>DUCK </b></td></tr><tr><td>Address:</td><td><span>Anytown </span><span>NY </span><span>USA </span></td></tr><tr><td>Gender:</td><td>MALE</td></tr><tr><td>Birth Date:</td><td>15/06/1985</td></tr></tbody></table></div>"},"identifier":[{"system":"http://fhir.openmrs.org/ext/provider/identifier","value":"111aaabbc122334"}],"active":true,"name":[{"id":"bb9fe2fb-c4c4-444d-8e14-0fac3c3175b6","text":"Donald Duck","family":"Duck","given":["Donald"]}],"address":[{"id":"f393725e-44ee-48d1-8bc5-846589c224ae","use":"home","city":"Anytown","state":"NY","postalCode":"12345","country":"USA"}],"gender":"male","birthDate":"1985-06-15"}

Note: Same issue with Patient endpoint, having partially update and on updating address it is showing response as:

{
    "resourceType": "OperationOutcome",
    "text": {
        "status": "generated",
        "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><h1>Operation Outcome</h1><table border=\"0\"><tr><td style=\"font-weight: bold;\">ERROR</td><td>[]</td><td><pre>no such path in target JSON document</pre></td>\n\t\t\t</tr>\n\t\t</table>\n\t</div>"
    },
    "issue": [
        {
            "severity": "error",
            "code": "processing",
            "diagnostics": "no such path in target JSON document"
        }
    ]
}

@ibacher @mherman22

16

Do you have a copy of the server log?

17

server_logs.txt (12.4 KB)

Please help me to resolve this issue.

Will it work for both Practitioner and Patient ?

@ibacher @mherman22

18

The only immediate advice I have is to not use PATCH updates if you can’t get them working.

19

The JSON Document above is badly written hence the above failure you’re encountering. By the look of things, you are attempting a Json Patch and your document should look something like below for it to work!

[
    {
        "op": "replace",
        "path": "/gender",
        "value": "male"
    },
    {
        "op": "replace",  //change this to add if the original practitioner doesnt have address captured
        "path": "/address",
        "value": [
            {
                "city": "New City",
                "country": "USA",
                "postalCode": "458562",
                "state": "CA"
            }
        ]
    }
]

You can always borrow knowledge from how the test-data here was written. One other thing to watch out for is the content-type of either a json patch, json merge patch or xml patch. they are different.

1 Like
20

Shouldn’t an expression like /address/0/city correctly resolve as in this example?