Federated FHIR
Overview
The Federated FHIR Query Model enables seamless, on-demand clinical data retrieval directly from clients' systems. In this approach, our clients register patients within our system using FHIR resources or ADT messages. When an external entity submits a query for a registered patient, we act as a bridge, federating the request to the client’s server in real-time. This setup minimizes the need for data storage on our end, instead facilitating a secure, instantaneous data exchange directly from the client, ensuring up-to-date information and maintaining data control within the client’s environment. There are 4 steps to the Federated FHIR process:
- Registering the patient in the Health Gorilla MPI/RLS via an ADT or POST to the Patient API.
- Returning an access token to an Oauth 2.0 client credential request from Health Gorilla
- Answering a DocumentReference FHIR request for a patient.
- Returning a document in response to a Binary request from Health Gorilla.
Workflow
- The client will register each patient in their Health Gorilla (and by extension the Health Gorilla Master Patient Index (MPI) and Record Locator Service(RLS) using the Health Gorilla FHIR Patient API.
- When an incoming query is received from another QHIO, Health Gorilla will use the MPI and RLS to locate the patient in the client's Health Gorilla tenant and initiate the federated query process.
- Health Gorilla will send an Oauth request to the client's Oauth server to obtain an access token.
- The access token will then be used to make a request to the client's FHIR server to retrieve a FHIR Bundle containing a list of DocumentReference resources representing the list of documents available for the patient.
- Health Gorilla will make this list available to the querying QHIO.
- The binary links in the list can be used to retrieve the actual documents from the client's FHIR repository.
Patient Management
Overview
Patient management is handled using the Health Gorilla FHIR APIs. The following sections will detail the processes for: Creating an access token, creating a patient with the needed demographics, and updating the patient. Patient Create Health Gorilla Dev Guide
Oauth Credentials
Health Gorilla follows the Oauth 2.0 JWT authorization process. A JWT is created and signed with the client secret provided by Health Gorilla. This signed JWT becomes an assertion that is used to retrieve an access token from the Health Gorilla authorization server. The retrieved access token is then provided in the request Authorization header in each request made to Health Gorilla. Oauth 2.0 Health Gorilla Dev Guide
Patient Creation
Health Gorilla allows for the registry of new patients via a POST to the Patient FHIR endpoint (baseURL/FHIR/R4/Patient). The post contains a Patient FHIR resource with the following demographics: First Name, Last Name, DOB, Gender (male/female), Address and a unique ID for the patient in the user’s system. **This unique identifier is the identifier that will be used by Health Gorilla in the federated DocumentReference query to the customer’s server.** The ID will have an accompanying system identifier which can be the URL of the customer or a unique OID generated by an authorized organization. Email and phone numbers are encouraged, but not required. These extra demographics can aid in patient matching.
{
"resourceType": "Patient",
"identifier": [
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "PT",
"display": "Patient external identifier"
}
],
"text": "Patient external identifier"
},
"system": "{{client_uri}}", //this will be either the client's website or an actual urn:oid:xxxxxx
"value": "{{mrn}}" //the actual patient ID in the customer's system
}
],
"name": [
{
"use": "usual",
"family": "{{patientLastName}}",
"given": [
"{{patientFirstName}}"
]
}
],
"address": [
{
"use": "home",
"type": "both",
"text": "123 Fake Street, CA 90402",
"line": [
"123 Fake Street"
],
"city": "Monica",
"state": "CA",
"postalCode": "90402",
"period": {
"start": "1988-10-15"
}
}
],
"gender": "male/female",
"birthDate": "1990-06-08",
"telecom": [
{
"use": "home"
},
{
"system": "phone",
"value": "(111) 111 1111",
"use": "work",
"rank": 2
},
{
"system": "phone",
"value": "(111) 111 1111",
"use": "mobile",
"rank": 1
},
{
"system": "email",
"value": "[email protected]",
"use": "work"
}
]
}
Federated Query
Overview
When Health Gorilla receives a query from a QHIO, a check will be done against the Health Gorilla MPI/RLS to determine if the patient exists in the client's tenant. If the patient is found, Health Gorilla will initiate the federated query process. The process is composed of the following: an Oauth call, a DocumentReference call, and calls to retrieve the actual documents for the patient.
Oauth 2.0
Health Gorilla supports the Oauth 2.0 client credential flow for authenticating to the client's FHIR server.
- Client Credential call to client'sOauth server
Health Gorilla will send the following call to the client's Oauth endpoint. The client ID and secret will be provided by client to Health Gorilla.
POST /token HTTP/1.1
Host: authorization-server.com
grant_type=client_credentials
&client_id=xxxxxxxxxx
&client_secret=xxxxxxxxxx
&aud=xxxxxxxx
&scope=xxxxxxx
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"access_token":"MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
"token_type":"Bearer",
"expires_in":3600,
"refresh_token":"IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTVk",
"scope":"create"
}
DocumentReference Call
-
Health Gorilla Request
Health Gorilla will make a DocumentReference call to the FHIR URL provided by the client. This call will contain the Access token in the REQUEST Authorization header in the format: Authorization:Bearer <access token>
The request will be:
<baseURL>/DocumentReference?patient=<client's ID of patient>
-
Client's Response
The FHIR server should respond with a status code of 200 if the request is successful regardless of if documents are found. The response should be a FHIR Bundle payload. With no documents found, the Bundle.total = 0.
Example FHIR Bundle payload:
{
"resourceType": "Bundle",
"type": "searchset",
"total": 1,
"link": [
{
"relation": "self",
"url": "baseURL/v1/uscore/R4/DocumentReference?patient=<TridentCareID>"
}
],
"entry": [
{
"fullUrl": "baseURL/v1/uscore/R4/DocumentReference/e60db908-8ca4-4d20-168c-277068800c61",
"resource": {
"resourceType": "DocumentReference",
"id": "e60db908-8ca4-4d20-168c-111111",
"contained": [
{
"resourceType": "Organization",
"id": "crs0",
"identifier": [
{
"value": "2.16.840.1.113883.3.239.23.90"
}
],
"active": true,
"name": "Test Hospital",
"telecom": [
{
"system": "phone",
"value": "tel:+1(111)-111-1111",
"use": "work"
}
],
"address": [
{
"use": "work",
"line": [
"123 Test Street"
],
"city": "East York",
"state": "TX",
"postalCode": "77706",
"country": "United States"
}
]
},
{
"resourceType": "Organization",
"id": "crs1",
"active": true,
"name": "Test Hospital",
"telecom": [
{
"system": "phone",
"value": "tel:+1(111)-111-1111",
"use": "work"
}
],
"address": [
{
"use": "work",
"line": [
"123 Test Street"
],
"city": "East York",
"state": "ON",
"postalCode": "77706",
"country": "United States"
}
]
}
],
"masterIdentifier": {
"system": "urn:oid:2.16.840.1.113883.3.239.23.90",
"value": "2563"
},
"identifier": [
{
"use": "usual",
"system": "urn:ietf:rfc:3986",
"value": "urn:uuid:e60db908-8ca4-4d20-168c-277068800c61"
}
],
"status": "current",
"type": {
"coding": [
{
"system": "http://loinc.org",
"code": "34133-9",
"display": "Summarization of episode note"
}
],
"text": "Summarization of episode note"
},
"category": [
{
"coding": [
{
"system": "http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category",
"code": "clinical-note",
"display": "Clinical Note"
}
]
}
],
"subject": {
"reference": "Patient/<Client_Patient_ID>",
"type": "Patient",
"display": "<Client_Patient_ID>"
},
"date": "2023-08-25T17:40:12+00:00",
"author": [
{
"reference": "#crs0",
"type": "Organization",
"display": "Test Hospital"
}
],
"custodian": {
"reference": "#crs1",
"type": "Organization",
"display": "Test Hospital"
},
"securityLabel": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-Confidentiality",
"code": "N",
"display": "normal"
}
],
"text": "normal"
}
],
"content": [
{
"attachment": {
"contentType": "application/xml",
"language": "en-US",
"url": "baseURL/v1/ccda-documents/e60db908-8ca4-4d20-168c-277068800c61?patient=<Clients_Patient_ID>",
"size": 33024,
"hash": "TRFD/SeqFMmdWL4/dBG+INxTxog="
},
"format": {
"system": "http://ihe.net/fhir/ValueSet/IHE.FormatCode.codesystem",
"code": "urn:hl7-org:sdwg:ccda-structuredBody:2.1",
"display": "For documents following C-CDA constraints using a structured body",
"userSelected": false
}
}
],
"context": {
"encounter": [
{
"reference": "Encounter/d7011ef9-0a7b-5541-84de-3f76f67e6c7f",
"type": "Encounter",
"display": "d7011ef9-0a7b-5541-84de-3f76f67e6c7f"
}
],
"event": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
"code": "GENRL",
"display": "General"
},
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
"code": "MED",
"display": "Medical"
}
]
}
],
"period": {
"start": "2023-05-27",
"end": "2023-08-25"
}
}
},
"search": {
"mode": "match"
}
}
]
}
Document Retrieval
Health Gorilla will send the access token in the Request header.authorization field in a request to the url found in the Resource.attachment.url field in each DocumentReference resource in the response Bundle above. The response should be the actual binary file of the document.
Updated about 1 month ago