Network Query (via IHE)
IHE, or "Integrating the Healthcare Enterprise," is a standards profiling organization that maintains best practices for exchanging healthcare data within and between various healthcare communities. These communities are often location-based and share patient consent agreements via nationwide health information exchange (HIE) networks such as Carequality and CommonWell. Querying these networks requires supplying patient demographics to search and retrieve information from various communities linked in the system.
To utilize networks that support the IHE protocol, your solution must provide a bidirectional path for fetching and sharing medical documents. In IHE, the term "Initiating Gateway" refers to finding and retrieving patient records from network communities. Your solution must also support the reverse data flow by providing records in your system back to other communities in the network when others are searching for patients with matching demographics. This is called a "Responding Gateway" in IHE. You can read more about these gateways in the IHE white paper.
OneRecord simplifies this process while using HealthShare Health Connect to make OneRecord API responsible for the communications required within the Initiating and Responding Gateways. To use the Initiating gateway, solutions only need to make OneRecord API calls to query for patient documents, and OneRecord and Health Share handle the complexities of securing these calls. To use the Responding Gateway, some part of your solution's back end must serve the required endpoints that respond with patient records when requested. These endpoints should be secured between your solution and OneRecord to ensure IHE compliance and enable your system to return records to the network when needed. For more information on setting this up, see "Setting up a Responding Gateway."
Querying Patient Records
Before proceeding with querying patient records using the Initiating Gateway, ensure that your OneRecord API account's Access Tokens are correctly configured and your responding gateway setup has been connected to OneRecord and verified as secure. Once your account is set up and connected to the networks, you can move forward with the following high-level steps:
- Use OneRecord API to search for records by providing patient demographics (e.g., first name, last name, date of birth, gender, zip code). This determines if any of the IHE networks supported by OneRecord contain documents for the given patient.
- Examine the metadata returned on any potential documents found in step 1 to decide which documents you would like to retrieve.
- Make OneRecord API calls to retrieve one or more of the documents of interest by providing information about the document, community, and repository obtained from the metadata received when querying for the existence of the documents.
- Unpackage and process the compressed document data by decoding the Base64 encoded string that represents the data.
While waiting for your account's API Access Token, you can use one of OneRecord's test Devices to continue setting up your integration. Following these steps will help you successfully fetch and process patient records through the Initiating Gateway.
Disclaimer: Registering Patients for CommonWell
Before querying records for patients with data served by CommonWell, it's essential to register the patient and their demographics. OneRecord API offers a Register Patient endpoint through the Integrator Service to facilitate this process.
Keep in mind that there's no harm in attempting to register a patient who is already registered, as the response will simply indicate that the patient is already in the system. However, it's beneficial for your solution to remember which patients have been registered to optimize the number of API calls made and improve the overall performance of your product and the network.
Try It Here, or Use the following Integrator Service URL:
POST https://stage.integrator.onerecord.com/integrator/v1/patient/register
Request Body:
{
"id": "8f0ca843-c2db-4124-8816-da5b8eab1fcb",
"firstname": "Pedro",
"lastname": "Martinez",
"dob": "1975-11-11",
"gender": "M",
"zip": "98042"
}
Example Patient Registration with Curl
curl --request POST \
--url https://stage.integrator.onerecord.com/integrator/v1/patient/register \
--header 'Accept: */*' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [provided jwt]' \
--data '{"id": "8f0ca843-c2db-4124-8816-da5b8eab1fcb","firstname":"Pedro","lastname":"Martinez","dob":"1975-11-11","gender":"M","zip":"98042"}'
Initiating a Network Query
To start a network query transaction, you'll need to supply the patient demographics to OneRecord API.
This will trigger a search within the IHE networks, and the response will return a list of all available documents
for retrieval. Take note of the following document properties in the response, as they will be required later when
retrieving the actual documents: structuredDocId, repositoryUniqueId, community, homeCommunityId and
communityId.
Try It Here, or Use the following Integrator Service URL:
POST https://stage.integrator.onerecord.com/integrator/v1/patient/documents
Request Body:
{
"firstname": "Teresa",
"lastname": "Reitman",
"dob": "1984-05-12",
"gender": "F",
"homephone": "9193789823",
"streetaddress": "215 Main Street",
"city": "Hoboken",
"state": "NJ",
"zip": "07030",
"filters": {
"organizationid": "urn:oid:2.16.840.1.113883.3.7080.2.4.1003.101"
}
}
Note
If an
organizationIdis not provided in the filters section, the system will query all endpoints in the provided
state. If the state is not provided andorganizationIdis also not provided the system will not know where to send
the query, it will return with an error.
Example Document Query with Curl
curl --request POST \
--url https://stage.integrator.onerecord.com/integrator/v1/patient/documents \
--header 'Accept: */*' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [provided jwt]' \
--data '{ "firstname": "Teresa", "lastname": "Reitman", "dob": "1984-05-12", "gender": "F", "homephone": "9193789823", "streetaddress": "215 Main Street", "city": "Hoboken", "state": "NJ", "zip": "07030", "filters": { "organizationid": "urn:oid:2.16.840.1.113883.3.7080.2.4.1003.101" } }'
The following is an example of a test patient's document results.
{
"gateways": [
{
"communityId": "2.16.840.1.113883.3.7080.2.4.1003.101",
"community": "CareQuality",
"documents": [
{
"createdDate": "2024-08-20T14:09:27Z",
"fileType": "text/xml",
"structuredDocId": "30ae89e6-72ba-48ee-b334-4361b1373b76",
"repositoryUniqueId": "2.16.840.1.113883.3.7080.2.4.1003.101.1",
"homeCommunityId": "2.16.840.1.113883.3.7080.2.4.1003.101",
"classCode": {
"code": "34133-9",
"codingScheme": "2.16.840.1.113883.6.1",
"names": [
{
"valueText": "Summary of episode note"
}
]
},
"name": "Transition of Care/Referral Summary"
},
{
"createdDate": "2024-08-20T14:09:27Z",
"fileType": "application/pdf",
"structuredDocId": "dc6e10c7-7f21-43bf-8c99-c87839d4c49b",
"repositoryUniqueId": "2.16.840.1.113883.3.7080.2.4.1003.101.1",
"homeCommunityId": "2.16.840.1.113883.3.7080.2.4.1003.101",
"classCode": {
"code": "18776-5",
"codingScheme": "2.16.840.1.113883.6.1",
"names": [
{
"valueText": "Plan of care note"
}
]
},
"name": "PDF Patient Record: Teresa Reitman"
}
],
"queryDocumentExecutionTime": 1.178,
"queryPatientExecutionTime": 13.413,
"state": "DOCRETRIEVES",
"totalDocs": 5
}
],
"id": "5468468451546468"
}
Retrieving Document(s)
Once you have the necessary document metadata from the previous step, you can use OneRecord API through the Integrator
Service to retrieve one or more documents at once. Provide the appropriate metadata for the desired document(s) to
initiate the retrieval process.
Try It Here, or Use the following Integrator Service URL:
POST https://stage.integrator.onerecord.com/integrator/v1/document/retrieve
Request Body:
[
{
"communityId": "2.16.840.1.113883.3.7080.2.4.1003.101",
"homeCommunityId": "2.16.840.1.113883.3.7080.2.4.1003.101",
"community": "CAREQUALITY",
"documentId": "30ae89e6-72ba-48ee-b334-4361b1373b76",
"repositoryUniqueId": "2.16.840.1.113883.3.7080.2.4.1003.101.1"
}
]
Note
Some Carequality implementers use the parent organization for document query and downstream organization for retrieve.
In these cases thehomeCommunityIdmay differ from thecommunityId. You simply send these values as they come from the document query response.
Requirement
The Document Retrieve transaction is issued based on a successful response from a document query which contains a
common header with theOneRecord-Transaction-IDof the Document Query transaction. The Document Retrieve request
MUSTcontain this transaction id from the document query in a header namedOneRecord-Transaction-ID-PARENT.
If not provided the caller will receive a 400 error indicating a bad request due to the missing header.
Example Document Retrieval with Curl
curl --request POST \
--url https://stage.integrator.onerecord.com/integrator/v1/document/retrieve \
--header 'Accept: */*' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [provided jwt]' \
--data '[ { "communityId": "2.16.840.1.113883.3.7080.2.4.1003.101", "homeCommunityId": "2.16.840.1.113883.3.7080.2.4.1003.101", "community": "CAREQUALITY", "documentId": "30ae89e6-72ba-48ee-b334-4361b1373b76", "repositoryUniqueId": "2.16.840.1.113883.3.7080.2.4.1003.101.1" } ]'
The body of this response is a base64 encoded string which, when decode
[
{
"errorData": null,
"availabilityStatus": null,
"structuredDocId": "30ae89e6-72ba-48ee-b334-4361b1373b76",
"repositoryUniqueId": "2.16.840.1.113883.3.7080.2.4.1003.101.1",
"homeCommunityId": "2.16.840.1.113883.3.7080.2.4.1003.101",
"communityId": "2.16.840.1.113883.3.7080.2.4.1003.101",
"community": "CAREQUALITY",
"body": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4...",
"errors": null
}
]
After retrieving the documents, you'll receive a base64 encoded string in the response body. When decoded, this string represents the data of the document. Documents can be in various formats. The most popular formats are CDA XML documents or PDF documents, but sometimes the decoded result can be an image or something else.
Note
Do not use online base64 decoders with production-level PHI data. Your solution should use a secured mechanism for decoding medical data.
You can download full examples of the various document types from the Data Sources Page.
Setting Up a Responding Gateway
In most cases, solutions connecting to networks via IHE must support a Responding Gateway. Your solution must be able to participate in network searches, providing records when others in the network find and request them. The only scenario in which a Responding Gateway is not required would be for solutions like clinical trials, where no new patient records are being stored, and records are only ever queried. This will be determined as part of your solution's Certification Process.
How The Responding Gateway Works
To set up a Responding Gateway, your solution must enable patients and documents to be queryable and retrievable. There are three main requirements that must be supported:
- Patient Lookup Query (via Demographics): For Carequality only, this identifies whether a patient with matching demographics exists within OneRecord API's customer data repository.
- Document Gateway Query: This identifies if your solution houses data for a patient (typically registered in Commonwell or Carequality).
- Document Retrieval: This retrieves the actual data of a document found in the previous step with OneRecord API's customer data repository.
You, as the solution provider must set up the appropriate means to retrieve and reliably serve these endpoints so that OneRecord API can maintain constant contact with your systems, upholding the commitment to enabling IHE transactions. OneRecord API authenticates to your solution's system and calls these endpoints as network searches are performed.
Testing Your Responding Gateway Configuration and Communication with OneRecord API
Setting up your Responding Gateway is an essential step in the onboarding process if you wish to connect with healthcare interoperability networks. As part of this process, your developers will provide OneRecord with a secure means of authenticating with their endpoints, which are listening for requests from the network.
To test your Responding Gateway's functionality and communication with OneRecord API, first complete and internally test your team's implementation of the required endpoints. Then, for each OneRecord API environment (Stage, Pre-Production, and Production), provide OneRecord with the corresponding URLs that fulfill the Responding Gateway requirements, along with the steps for securely authenticating with your endpoints.
Once OneRecord API has your information configured, you can use the "Responding Gateway" calls with OneRecord API Reference to trigger test calls to each of your Responding Gateway endpoints at any time. Be sure to use the appropriate Integrator Service base URL for the OneRecord environment in which you are attempting to test your gateway endpoints, their configuration, and connection through OneRecord API. By default, the API Reference uses the Stage environment.
Performing these tests will help you refine your patient search algorithms and optimize internal logistics for document queries and retrievals, ensuring that your Responding Gateway is correctly set up and able to communicate effectively with OneRecord API.
Supporting the Patient Lookup Query
To support the Patient Lookup Query for the Responding Gateway, your solution must be able to handle requests whenever users search for establishments connected to the Carequality IHE network that have potentially interacted with a specific patient. CommonWell, on the other hand, uses a different patient registration mechanism. Clients query CommonWell for a linked patient match and need not rely on this endpoint for patient lookups.
Your endpoint should accept patient demographics as input and return relevant search results containing a match score and the patient's local identifier in your system. Carequality uses this local patient identifier to make any subsequent document queries requested in your system for the given patient.
Your development team integrating with OneRecord API is responsible for architecting the algorithm that returns meaningful results from your system and maintaining reliable uptime. The following example outlines the minimum requirements for the demographics properties your endpoint must be able to match upon.
GET https://<your-app-url>/<path-for your-patient-lookup-endpoint>
Request Body:
{
"firstname":"String",
"lastname":"String",
"dob":"yyyy-MM-DD",
"gender":"[M|F|U]",
"homephone":"String",
"streetaddress":"String",
"city":"String",
"state":"String(2)(Stateabbreviation)",
"zip":"String",
"requestingOrganizationId":"String(OIDformat)",
"timestamp":"int",
"requestor":"[CommonWell|Carequality]"
}
The response should a list of patient matches with a match score for each:
[
{
"gender":"[M|F|U]",
"dob":"yyyy-MM-DD",
"city":"String",
"state":"String(2)(Stateabbreviation)",
"zip":"String",
"firstname":"String",
"lastname":"String",
"homephone":"String",
"streetaddress":"String",
"patientid":"String",
"matchScore":"String"
}
...
]
Supporting the Document Gateway Query
Once a valid patientId is obtained from the previous patient discovery query, additional information about the documents stored for that patientId can be requested. This request is sent to OneRecord through HealthShare Health Connect, specifying the patientId. To test your Responding Gateway setup, you can try it here.
Your development team is responsible for implementing the required endpoint that listens to OneRecord on behalf of these HealthShare requests. Here's an example request and response for the integrator's endpoint:
GET https://[integrator-url]/integrator/v1/gateway/patient/documents
Request Body:
{
"patientId":"{{ihe-gateway-patient-id}}",
"patientIdentityAssigningAuthority":"{{ihe-gateway-patient-aa}}",
"requestingOrganizationId":"{{ihe-network-client-organization-oid}}",
"timestamp":"1639775987621",
"requestor":"CommonWell",
"reason":"Treatment",
"requestingParty":"CommonWell",
"disclosingParty":"OneRecord"
}
Your endpoint is expected to return the following response structure:
{
"gateways":[
{
"communityId":"2.16.840.1.113883.3.7080.2.4.1003.101.300",
"documents":[
{
"status":"APPROVED",
"createdDate":"11-02-202214:52:40",
"fileType":"text/xml",
"classCode":{
"code":"34133-9",
"codingScheme":"2.16.840.1.113883.6.1",
"text":"Summaryofepisodenote"
},
"name":"TransitionofCare/ReferralSummary",
"authorPerson":"Dr.Who",
"authorInstitution":"TestMedicalCenter^^^^^^^^^2.16.840.1.113883.3.7080.2.4.1003.101.300",
"confidentialityCode":{
"text":"Normal"
},
"formatCode":{
"code":"urn:ihe:pcc:xphr:2007",
"codingScheme":"1.3.6.1.4.1.19376.1.2.3"
},
"healthcareFacilityTypeCode":{
"code":"310205006",
"codingScheme":"2.16.840.1.113883.6.96",
"text":"Privateresidentialhome"
},
"practiceSettingCode":{
"code":"394733009",
"codingScheme":"2.16.840.1.113883.6.96",
"text":"Medicalspecialty--OTHER--NOTLISTED"
},
"typeCode":{
"code":"51855-5",
"codingScheme":"2.16.840.1.113883.6.1",
"text":"PatientGeneratedDocument"
},
"documentUniqueId":"654e3f75-cecf-4e65-b57f-90bffc0612cb",
"patientId":"ORAPI-TEST-5555",
"patientIdentityAssigningAuthority":"2.16.840.1.113883.3.7080.2.4.1003.101.300.1",
"repositoryUniqueId":"2.16.840.1.113883.3.7080.2.4.1003.101.300.1",
"onDemandDocument":true
}
]
}
]
}
In the response, the elements homeCommunityId, repositoryUniqueId, and documentUniqueId are essential for retrieving documents through the Responding Gateway. These values should already exist within your system, and your document retrieval algorithm should be designed to use them to locate the requested document. This ensures a seamless and efficient process for retrieving healthcare documents from your system when interacting with OneRecord API and the healthcare interoperability networks.
Supporting Document Retrieval
Once document identifiers have been obtained through the Document Query endpoint, they can be used to retrieve the raw data for any of those documents. A single document retrieval request can contain instructions to retrieve one or multiple documents, so it's essential that your endpoint responds with data for all requested documents.
The call from the network will be sent through Health Connect by HealthShare, which parses the IHE message and calls OneRecord API according to the following inputs and outputs:
GET https://[integrator-url]/integrator/v1/gateway/document/retrieve
Request Body:
{
"documents":[
{
"repositoryUniqueId":"2.16.840.1.113883.3.7080.2.4.1003.101.300.1",
"documentUniqueId":"654e3f75-cecf-4e65-b57f-90bffc0612cb",
"homeCommunityId":"2.16.840.1.113883.3.7080.2.4.1003.101.300"
}
],
"timestamp":"1639775987621",
"requestor":"CommonWell",
"reason":"Treatment",
"requestingParty":"123.1.3.2.3.4.5",
"disclosingParty":"123.1.3.2.3.4.5"
}
Your endpoint is expected to return the following response structure:
[
{
"documentUniqueId":"654e3f75-cecf-4e65-b57f-90bffc0612cb",
"newDocumentId":"654e3f75-cecf-4e65-b57f-90bffc0612cb",
"communityId":"2.16.840.1.113883.3.7080.2.4.1003.101.300",
"repositoryUniqueId":"2.16.840.1.113883.3.7080.2.4.1003.101.300.1",
"patientId":"ORAPI-TEST-5555",
"patientIdentityAssigningAuthority":"2.16.840.1.113883.3.7080.2.4.1003.101.300.1",
"document":"<base64encodedstring>"
}
]
The "document" property in the response contains a base64 encoded string that holds the data for the medical document. Once decoded, the content of the document may include CDA data in an XML format, PDF, images, or various other document types. Make sure your development team has implemented an efficient and reliable algorithm for retrieving and serving these documents as base64 encoded strings in response to OneRecord API requests. This will ensure seamless interaction between your system and the healthcare interoperability networks, ultimately providing the necessary medical data to authorized parties.
Wrapping Up
This guide has demonstrated how OneRecord API simplifies the integration process with vast and complex networks like Carequality and CommonWell, providing a streamlined path for accessing patient records across participating communities. By leveraging OneRecord API, developers can efficiently connect to these networks, enabling a wide reach into a growing number of healthcare communities both now and in the future. For more specific details on Carequality and CommonWell, please refer to the Partner Networks Page
Updated 4 months ago