Facility Registry Implementation Guide
0.1.0 - ci-build
Facility Registry Implementation Guide
0.1.0 - ci-build
Facility Registry Implementation Guide - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
The primary purpose of the LK Facility Registry (FR) is to manage health care Facilities. Managing Facility identities is composed of the following major responsibilities:
Queries such as
are common. FHIR offers many possibilities to associate the above Resources. This guide will limit the the associations such that queries are straightforward and the structure consistent, yet still cover the common queries.
The link between Practitioners and HealthcareServices, Organizations and Locations is created by a PractitionerRole instance that is populated with HealthcareService References.
Based on the above commentary the following statements must be true and these statements constrain the Resource associations to a limited set:
Each HealthcareService Resource
Each PractitionerRole Resource (that links to HealthcareServices)
The resulting structure is as follows;
This structure fits many different hierarchies. For example a Hospital and general family practice may be modeled as follows:
┌──────────────────────┐
│ ORGANIZATION │
│ │
│Hemas Hospital Wattala│
└──▲────────────────▲──┘
│ │
│ │
┌───────────────┐ ┌────────────────┐ ┌────────────┐ ┌───────────────────┐
│ ORGANIZATION │ │ ORGANIZATION │ │PRACTITIONER│ │ ORGANIZATION │
│ │ │ │ │ ◄─────────────┐ │ │
│Emergency Dept.│ │Cardiology Dept.│ │ Dr. Jagath │ │ │Jagath Health Inc. │
└──────▲────────┘ └───────▲────────┘ └─────▲──────┘ │ └───────▲───────────┘
│ │ │ │ │
│ │ │ │ │
┌────────┴─────────┐ ┌────────┴──────────┐ ┌──────┴─────────┐ ┌─────┴──────────┐ ┌─────────────────┐
│ HEALTHCARESERVICE│ │ HEALTHCARESERVICE │ │PRACTITIONERROLE│ │PRACTITIONERROLE│ │HEALTHCARESERVICE│
│ │ │ │◄─────┤ │ │ ├─────► │
│Emergency Services│ │Cardiology Services│ │ Cardiology │ │Family Practice │ │ General Practice│
└──────────────────┘ └──────┬────────────┘ └────────────────┘ └────────────────┘ └─────────────────┘
│ │ │
│ │ │
┌───▼──────────────────────▼───┐ │
│ LOCATION │ ┌──────────────▼─────────────┐
│ │ │ LOCATION │
│389 Negombo - Colombo Main Rd,│ │ │
│Wattala 11300, Sri Lanka │ │ 705 Old Negombo Rd, Wattala│
└──────────────────────────────┘ └────────────────────────────┘
Consideration 🔎 The Detailed Software Requirements Specification for Facility Registry document, dated February 2024, breaks down Facilities into institutions and units. Units may be modeled as Organizations in a hierarchical structure, as the diagram just above demonstrates but with departments in a hospital.
Consideration 🔎 The queries below assume Organization records, Services and Location records are stored in a single repository and only relative References are required. Also that _include and _revinclude need only relative URLs. If Organization records, Services and Location records are separated into three Registries, the queries will still work and but require more steps to fetch all the requested Resource instances.
What Services does this Provider offer?
GET [base]/PractitionerRole?_include=PractitionerRole:service&practitioner=Practitioner/123
The above query would be requested of the Provider Registry as it returns a PractitionerRole. However with the _include parameter the Provider Registry, to complete the query, would need to contact the Facility Registry to GET the HealthcareServices. This is likely an over complicated design and alternatively this could be divided into several requests, one for Provider Registry and several more for the Facility Registry, one for each Service, as follows:
GET [base]/PractitionerRole?practitioner=Practitioner/123
GET [base]/HealthcareService?_id=123
GET [base]/HealthcareService?_id=321
What Services are offered at this Location?
GET [base]/HealthcareService?location=Location/123
What Organizations offer this Service?
GET [base]/HealthcareService?service-type=#64&_include=HealthcareService:organization
Where is the closest Pharmacy?
GET [base]/Location?near=…&_has:HealthcareService:location:service-type=#64&_revinclude=HealthcareService:location
Where is this Provider working?
This is a multi-step process, first get Service References from Provider Registry, then request HealthcareServices from the Facility Registry which can include Locations.
GET [base]/PractitionerRole?practitioner=Practitioner/789
GET [base]/HealthcareService?_id=123&_include=HealthcareService:location
GET [base]/HealthcareService?_id=321&_include=HealthcareService:location
Who is this Provider working for?
This is a multi-step process, first request retrieves Service References from Provider Registry, then request HealthcareServices from the Facility Registry which can include Organizations.
GET [base]/PractitionerRole?practitioner=Practitioner/789
GET [base]/HealthcareService?_id=123&_include=HealthcareService:organization
GET [base]/HealthcareService?_id=321&_include=HealthcareService:organization
Consideration 🔎 This query, if there were independent Registries for Organization and Services, could be split into several searches:
GET [base]/PractitionerRole?practitioner=Practitioner/789
GET [base]/HealthcareService?_id=123
GET [base]/HealthcareService?_id=321
GET [base]/Organization?_id=987
GET [base]/Organization?_id=789
Consideration 🔎 These rules do not allow a Provider to be employed without specifying a Service. E.g. first one must setup a family practice clinic by creating the Location, the Organization and then the HealthcareService referencing the Location and Organization. The final steps create the PractitionerRole, with PractitionerRole referencing the HealthcareService and Practitioner instance.
Improvement 🔎 Removing a HealthcareService may orphan a PractitionerRole. It may be advantageous to manage the HealthcareServices and PractitionerRoles using FHIR Operations to ensure that the relationships remain consistent. An alternative approach is to execute reports that identify orphaned Resources and notify an administrative team to address.
Consideration 🔎 It may be advantageous to develop an API that simplifies the multi-step queries between Registries by using an orchestration engine. For example Who is this Provider working for? is a multi-step query: (1) first query for the PractitionerRoles from Provider Registry, then (2) HealthcareService from Facility Registry and then (3) Organization from Facility Registry. A FHIR Operation could be developed that is implemented by an orchestration layer and executes all the necessary queries. There is no need to hide the low-level queries each Registry offers (this guide), but an API (facade design pattern) would encourage integration as the queries are simple and allow security to be a little more refined, i.e. allow access to FHIR Operation API and not all Registries.
Caution 🔎 Orchestration of FHIR queries and combining the results does pose some additional complexities that don't exist otherwise. E.g. Does one FHIR repository return only active records, while another returns non-active as well? How do the user security permissions translate across FHIR repositories? What to do when there are too many results returned — which to discard? How should the query behave if one FHIR repository is offline or doesn't respond quick enough?
Connected systems SHALL use the FHIR Restful specification to access Practitioner instances, limited as described in this guide. Specific Operations, as defined in this guide, SHALL be used to interact with the PR. The limited interfaces offered by the PR are described in the detailed specification.