OpenMRS Support for a FHIR-based Facility Registry

OpenMRS Support for a FHIR-based Facility Registry: A Concept Note

This post is meant to serve as an overview and concept note for the OpenMRS Facility Registry project. Any and all questions, suggestions, or concerns are welcome!


  1. Enable OpenMRS to act as a client (or Care Services Update Consumer) of a Facility Registry like GoFR.

  2. Enable OpenMRS to upload and synchronize the implementation-specific Location hierarchy with a centralized Facility Registry.

Proposed Tasks

(See the Facility Registry Workflow Epic for related issues)

1. Determine what OpenMRS support for the mCSD profile looks like:

  • How would external facility lists be used within current OpenMRS Workflows?
  • Would OpenMRS be solely a consumer of Facility Registry data, or would there be a need to upload data as well?
  • Does the scope of the mCSD profile align with the OpenMRS approach to locations, referrals, and healthcare service information?
  • etc…

2. Explore the mappings between the mCSD Data Model and the OpenMRS Location Hierachy.

Related Issues: FM2-433, FM2-434

Draft Mapping Spreadsheet: mCSD -OpenMRS FHIR Mappings - Google Sheets

3. Document the proposed OpenMRS FHIR Module support for mCSD-related resources in the FHIR2 Module Implementation Guide.

IG Github: GitHub - openmrs/openmrs-contrib-fhir2-ig: Implementation Guide for the FHIR2 module CI Build:

4. Add functionality for OpenMRS to consume and cache FR data

Any relevant information obtained from the FR can be stored as tagged Locations in the OpenMRS data model. We can leverage custom attributes to add required data that does not currently have dedicated support in the OpenMRS Location class.

5. Demonstrate the use of FR data in one of the target OpenMRS Use Cases

See below

6. Determine the utility of being able to synchronize the OpenMRS Location hierarchy with a centralized representation.

Similar to communication with a Client Registry or Terminology Service.

7. Implement any required but not implemented FHIR2 module support for FR workflows

The FHIR2 Module should support:

  1. Creating and updating a local representation of a FR dataset as an independent Location hierarchy
  2. Translating the OpenMRS Location hierarchy into a FR-compatible form for upload into a GoFR partition

8. Develop an IG-based testing framework for validating OpenMRS support for the mCSD profile and the related FR workflows.

  1. Overview of FHIR Implementation Guides: HL7.FHIR.UV.HOWTO\IG Home Page - FHIR v4.0.1
  2. Official FHIR IG Documentation: ImplementationGuide - FHIR v4.0.1
  3. Way of Working Artifact Metamodel: HL7.BE.FHIR.WOW\Home Page - FHIR v4.0.1
  4. OpenHIE Testing Concept Note
  5. Testing (against) FHIR Specifications

OpenMRS Facility Registry Use Cases

  • drop down population in UI
  • reporting
  • referrals
  • transfer in/outs
  • source of required information - Facility ID (national identifier not internal), Name, Address/Location, Active/Not-active, Services Offered, Facility Type

Challenges and Open Questions

  1. To what extent does the scope of our work overlap with the efforts to provide referral functionality in OpenMRS? (See Referrals in OpenMRS for more context)
  2. How should we architect the communication and use of centralized HIE components such as a Facility Registry, Client Registry, or Terminology Service by OpenMRS in general?
    • Should data from these sources be integrated with the OpenMRS data model?
    • Should OpenMRS strictly act as a consumer of these resources?
    • In what cases does instance-specific data need to be uploaded from OpenMRS to such a service?

FHIR Data Model for Facility Registry Data


  1. (Draft) Concept Note - Facility Registry IG - Google Docs
  2. IHE.MCSD.FHIR\mCSD Home Page - FHIR v4.0.1
  3. Target mCSD Use Case - Master Facility List
  4. Index - GOFR Documentation
  5. Working with FHIR - GOFR Documentation

Thanks @pmanko do you want to create a wiki page for this too where you will organize things

As discussed on today’s Platform Team call, we can add location.type as a Concept to link between physical locations / facilities and the more abstract (types of) locations needed for most referrals.

We expect that most orderable concepts will have the service pre-coordinated (e.g., “Physical Therapy referral” or “Cardiology referral”). So, a location/department would be implied within the orderable concept for most standard referrals. When a location is needed for a referral, we plan on using concepts. Those concepts could be optionally linked to specific locations through location.type.

I would expect the primary use wouldn’t be directly using a FR within OpenMRS application; rather, creating tooling – as you suggest – to help an OpenMRS instance import locations from a FR and export locations to a FR – i.e., simplify the process of aligning locations used within OpenMRS with locations being managed or centralized within a HIE’s FR.


@herbert24 I created a Wiki page under the FHIR Wiki: Facility Registry Workflows - Projects - OpenMRS Wiki

Let me know what you think!