Clinical Data Exchange-Tech

This document provides a comprehensive guide for integrating a hospital or clinic EMR system with FreeSHR, a centralized Health Information Exchange (HIE) component. The integration ensures that patient encounters are accurately synchronized and stored, leveraging standardized medical terminologies. This enables seamless data exchange and interoperability across different healthcare systems.

Overview of SHR Development

The SHR (Shared Health Record) system is designed with a microservices architecture, consisting of two main services:

SHR Main Service: Handles the creation and updating of encounters, and retrieves encounters by patient, catchment area, or individual encounter. It uses a Cassandra database and can be scaled with multiple nodes for higher loads.
FreeSHR Update Service: Updates patient information cached in SHR by subscribing to an update feed from the Master Client Index (MCI). It uses a MySQL database to maintain feed status and updates patient data in Cassandra.

Steps for Pushing Data from a Hospital to Central HIE

Synchronize Terminologies:
- Fetch and update the latest terminologies from the central Terminology Registry using Atom Feeds.
- Optionally, develop a local terminology mapping service to ensure consistency between local and central terminologies.
Construct FHIR Bundle:
- Create a FHIR bundle for the patient encounter using the synchronized terminologies.
- Validate the bundle to ensure it adheres to FHIR standards.
Submit FHIR Bundle to FreeSHR:
- Send the constructed FHIR bundle to the FreeSHR service endpoint.
- Handle the response to confirm successful submission or manage errors.
SHR Main Service Processing:
- The SHR Main Service processes the incoming FHIR bundle, updating the Cassandra database with the new encounter information.
FreeSHR Update Service:
- The FreeSHR Update Service monitors updates from the MCI and ensures patient information in SHR is current by updating the Cassandra database.

Detailed Integration Steps

For a detailed process of integrating new terminologies and pushing data from a hospital to the central HIE, refer to the following resources:

Format

The API is based on REST convention and uses HL7 FHIR format for exchange of data. Source https://hl7.org/fhir/stu3/

Authentication

All APIs described below need authentication. The client-id and From are given when registering with the Identity Provider. The signin API of Identity Provider should be used to get the auth token(To be provided in the X-Auth-Token header).

API Endpoints:

Base API:

Dev server:

SSO: https://dev.hris.survport.com/api/1.0/sso/signin

MCI : http://mci.mcishr.dghs.gov.bd

Encounter : https://shr.mcishr.dghs.gov.bd

TR : https://tr.mcishr.dghs.gov.bd

Facility : https://dev.hris.survport.com/api/1.0/facilities/{{facility-id}}.json

Provider : https://dev.hris.survport.com/api/1.0/providers/{{provider-id}}.json

Live server:

SSO: https://hrm.dghs.gov.bd/api/1.0/sso/signin

MCI : https://mci.shrlive.dghs.gov.bd/api/v1/patients

Encounter : https://shr.mcishr.dghs.gov.bd

TR : https://tr.shrlive.dghs.gov.bd

Facility : https://hrm.dghs.gov.bd/api/1.0/facilities/{{facility-id}}.json

Provider : https://hrm.dghs.gov.bd/api/1.0/providers/{{provider-id}}.json

Save an encounter.

Request :

POST {EncounterServer}/patients/{health Id}/encounters

Headers :

X-Auth-Token : {auth token returned from Identity Service Provider}

client-id : {client id of requester in Identity Service Provider}

From : {email_id of requester registered in Identity Service Provider}

Content-Type: application/xml;charset=utf-8

Example Bundle:

<meta>

</meta>

<entry>

</identifier>

<type>

</coding>

</type>

</subject>

</author>

</encounter>

<entry>

</entry>

</section>

</Composition>

</resource>

</entry>

<entry>

</identifier>

<class value=“field”/>

<type>

</type>

</patient>

</individual>

</participant>

</period>

</serviceProvider>

</Encounter>

</resource>

</entry>

</Bundle>

Example Bundle 2:

<meta>

</meta>

<entry>

</identifier>

<type>

</coding>

</type>

</subject>

</encounter>

</author>

<entry>

</entry>

</section>

<entry>

</entry>

</section>

<entry>

</entry>

</section>

</Composition>

</resource>

</entry>

<entry>

</identifier>

<class>

</class>

<type>

</coding>

</type>

</subject>

</period>

</serviceProvider>

</Encounter>

</resource>

</entry>

<entry>

</identifier>

</coding>

</category>

<code>

</coding>

</coding>

</code>

</subject>

</context>

</Condition>

</resource>

</entry>

<entry>

</identifier>

</coding>

</category>

<code>

</coding>

</code>

</subject>

</context>

</onsetPeriod>

</Condition>

</resource>

</entry>

</Bundle>

Sample Success Response :

{

“encounterId”: “9f81a363-ede1-4bd0-8af2-eb73045c9ab1”,

“errors”: [],

“successful”: true,

“errorResult”: null

}

Sample Failure Response:

{

“httpStatus”: “422”,

“message”: “Unprocessable entity : [{“field“:”f:Encounter/f:patient“,”type“:”invalid“,”reason“:”http://mci.mcishr.dghs.gov.bd/patients/9801098063:Patient Health Id does not match.”}]”,

“errors”: [

{

“field”: “f:Encounter/f:patient”,

“type”: “invalid”,

“reason”: “https://mci.shrlive.dghs.gov.bd/api/v1/patients/9801098063:Patient’s Health Id does not match.”

}

]

}

Get all encounters for a patient:

Request :

GET /patients/{health Id}/encounters

Headers :

X-Auth-Token : {auth token returned from Identity Service Provider}

client-id : {client id of requester in Identity Service Provider}

From : {email_id of requester registered in Identity Service Provider}

Accept: application/json(default)

Sample Response:

<?xml version=”1.0″ encoding=”UTF-8″?>

<feed

xmlns=”http://www.w3.org/2005/Atom”>

<title>Patient Encounters</title>

<link rel=”self” type=”application/atom+xml” href=”https://shr.mcishr.dghs.gov.bd/patients/98001095960/encounters” />

<link rel=”via” type=”application/atom+xml” href=”https://shr.mcishr.dghs.gov.bd/patients/98001095960/encounters” />

<author>

<name>FreeSHR</name>

</author>

<id>e82bb647-6372-40bd-a69f-f0cba0b576fd</id>

<generator uri=”https://github.com/ICT4H/atomfeed”>Atomfeed</generator>

<updated>2023-07-18T04:17:03Z</updated>

<entry>

<title>Encounter:bf5a744a-797e-4115-a065-6b6c09f19d89</title>

<link rel=”via” type=”application/xml” href=”https://shr.mcishr.dghs.gov.bd/patients/98001095960/encounters/bf5a744a-797e-4115-a065-6b6c09f19d89″ />

<category term=”encounter” />

<category term=”encounter_updated_at:2023-07-18T09:47:03.027+0530″ />

<id>7ace6830-4c9e-11e6-b8ee-ea409bb33e8c</id>

<updated>2023-07-18T04:17:03Z</updated>

<content type=”application/vnd.atomfeed+xml”>

<![CDATA[<Bundle

xmlns=”http://hl7.org/fhir”><id value=”0ccde14f-0047-4e9a-98bd-71f81991f6c2″/><meta><lastUpdated value=”2023-07-18T09:46:40.000+05:30″/></meta><type value=”collection”/><entry><fullUrl value=”urn:uuid:ac5c9949-d46d-4138-9966-356dab31520a”/><resource><Composition

xmlns=”http://hl7.org/fhir”><identifier><value value=”urn:uuid:ac5c9949-d46d-4138-9966-356dab31520a”/></identifier><date value=”2023-07-18T09:46:40.000+05:30″/><type><coding><system value=”http://hl7.org/fhir/vs/doc-typecodes”/><code value=”51899-3″/><display value=”Details Document”/></coding></type><title value=”Patient Clinical Encounter”/><status value=”final”/><confidentiality value=”N”/><subject><reference value=”https://mci.shrlive.dghs.gov.bd/api/v1/patients/98001095960″/><display value=”98001095960″/></subject><author><reference value=”https://dev.hris.survport.com/api/1.0/facilities/10019842.json”/></author><encounter><reference value=”urn:uuid:68cb6fd6-6e92-4720-9407-7d3df47ecd41″/></encounter><section><entry><reference value=”urn:uuid:68cb6fd6-6e92-4720-9407-7d3df47ecd41″/><display value=”Encounter”/></entry></section></Composition></resource></entry><entry><fullUrl value=”urn:uuid:68cb6fd6-6e92-4720-9407-7d3df47ecd41″/><resource><Encounter

xmlns=”http://hl7.org/fhir”><identifier><value value=”urn:uuid:68cb6fd6-6e92-4720-9407-7d3df47ecd41″/></identifier><status value=”finished”/><class value=”outpatient”/><type><text value=”REG”/></type><patient><reference value=”http://mci.mcishr.dghs.gov.bd/patients/98001095960″/><display value=”98001095960″/></patient><participant><individual><reference value=”https://dev.hris.survport.com/api/1.0/providers/20.json”/></individual></participant><period><start value=”2023-07-18T09:46:40.000+05:30″/></period><serviceProvider><reference value=”https://dev.hris.survport.com/api/1.0/facilities/10019842.json”/></serviceProvider></Encounter></resource></entry></Bundle>]]>

</content>

</entry>

<entry>

<title>Encounter:ccb7eb5d-66c7-4d4c-810b-2c6c7b8911b1</title>

<link rel=”via” type=”application/xml” href=”/patients/98001095960/encounters/ccb7eb5d-66c7-4d4c-810b-2c6c7b8911b1″ />

<category term=”encounter” />

<category term=”encounter_updated_at:2023-07-18T09:49:02.444+0530″ />

<id>c1fbfec0-4c9e-11e6-b8ee-ea409bb33e8c</id>

<updated>2023-07-18T04:19:02Z</updated>

<content type=”application/vnd.atomfeed+xml”>

<![CDATA[<Bundle

xmlns=”http://hl7.org/fhir”><id value=”39c0a368-04af-4ca9-89e2-78f183d7d63c”/><meta><lastUpdated value=”2023-07-18T09:48:00.000+05:30″/></meta><type value=”collection”/><entry><fullUrl value=”urn:uuid:63aace39-9348-4c43-bc7a-9485b9f3f2bc”/><resource><Composition

xmlns=”http://hl7.org/fhir”><identifier><value value=”urn:uuid:63aace39-9348-4c43-bc7a-9485b9f3f2bc”/></identifier><date value=”2023-07-18T09:48:00.000+05:30″/><type><coding><system value=”http://hl7.org/fhir/vs/doc-typecodes”/><code value=”51899-3″/><display value=”Details Document”/></coding></type><title value=”Patient Clinical Encounter”/><status value=”final”/><confidentiality value=”N”/><subject><reference value=”https://mci.shrlive.dghs.gov.bd/api/v1/patients/98001095960″/><display value=”98001095960″/></subject><author><reference value=”https://dev.hris.survport.com/api/1.0/facilities/10019842.json”/></author><encounter><reference value=”urn:uuid:25f16b01-af42-47e7-b3b7-cef40077dc0e”/></encounter><section><entry><reference value=”urn:uuid:25f16b01-af42-47e7-b3b7-cef40077dc0e”/><display value=”Encounter”/></entry></section><section><entry><reference value=”urn:uuid:29c25af3-9360-406a-abc3-00ed4102ba84″/><display value=”Immunization”/></entry></section></Composition></resource></entry><entry><fullUrl value=”urn:uuid:25f16b01-af42-47e7-b3b7-cef40077dc0e”/><resource><Encounter

xmlns=”http://hl7.org/fhir”><identifier><value value=”urn:uuid:25f16b01-af42-47e7-b3b7-cef40077dc0e”/></identifier><status value=”finished”/><class value=”outpatient”/><type><text value=”Consultation”/></type><patient><reference value=”http://mci.mcishr.dghs.gov.bd/patients/98001095960″/><display value=”98001095960″/></patient><participant><individual><reference value=”https://dev.hris.survport.com/api/1.0/providers/20.json”/></individual></participant><period><start value=”2023-07-18T09:46:40.000+05:30″/></period><serviceProvider><reference value=”https://dev.hris.survport.com/api/1.0/facilities/10019842.json”/></serviceProvider></Encounter></resource></entry><entry><fullUrl value=”urn:uuid:29c25af3-9360-406a-abc3-00ed4102ba84″/><resource><Immunization

xmlns=”http://hl7.org/fhir”><identifier><value value=”urn:uuid:29c25af3-9360-406a-abc3-00ed4102ba84″/></identifier><status value=”completed”/><date value=”2023-07-18T00:00:00.000+05:30″/><vaccineCode><coding><system value=”https://tr.mcishr.dghs.gov.bd/openmrs/ws/rest/v1/tr/drugs/e90ee3ac-83b0-11e5-aa01-0050568276cf”/><code value=”e90ee3ac-83b0-11e5-aa01-0050568276cf”/><display value=”BCG”/></coding></vaccineCode><patient><reference value=”https://mci.shrlive.dghs.gov.bd/api/v1/patients/98001095960″/><display value=”98001095960″/></patient><wasNotGiven value=”false”/><reported value=”true”/><requester><reference value=”https://dev.hris.survport.com/api/1.0/providers/20.json”/></requester><encounter><reference value=”urn:uuid:25f16b01-af42-47e7-b3b7-cef40077dc0e”/></encounter><doseQuantity><value value=”10.0″/></doseQuantity></Immunization></resource></entry></Bundle>]]>

</content>

</entry>

</feed>

Get a specific encounter for a patient:

Request :

GET /patients/{health Id}/encounters/{encounter id}

Headers :

X-Auth-Token : {auth token returned from Identity Service Provider}

client-id : {client id of requester in Identity Service Provider}

From : {email_id of requester registered in Identity Service Provider}

Accept: application/xml

Sample Response:

{

“content”: “<Bundle xmlns=\”http://hl7.org/fhir\”><id value=\”0ccde14f-0047-4e9a-98bd-71f81991f6c2\”/><meta><lastUpdated value=\”2023-07-18T09:46:40.000+05:30\”/></meta><type value=\”collection\”/><entry><fullUrl value=\”urn:uuid:ac5c9949-d46d-4138-9966-356dab31520a\”/><resource><Composition xmlns=\”http://hl7.org/fhir\”><identifier><value value=\”urn:uuid:ac5c9949-d46d-4138-9966-356dab31520a\”/></identifier><date value=\”2023-07-18T09:46:40.000+05:30\”/><type><coding><system value=\”http://hl7.org/fhir/vs/doc-typecodes\”/><code value=\”51899-3\”/><display value=\”Details Document\”/></coding></type><title value=\”Patient Clinical Encounter\”/><status value=\”final\”/><confidentiality value=\”N\”/><subject><reference value=\”https://mci.shrlive.dghs.gov.bd/api/v1/patients/98001095960\”/><display value=\”98001095960\”/></subject><author><reference value=\”https://dev.hris.survport.com/api/1.0/facilities/10019842.json\”/></author><encounter><reference value=\”urn:uuid:68cb6fd6-6e92-4720-9407-7d3df47ecd41\”/></encounter><section><entry><reference value=\”urn:uuid:68cb6fd6-6e92-4720-9407-7d3df47ecd41\”/><display value=\”Encounter\”/></entry></section></Composition></resource></entry><entry><fullUrl value=\”urn:uuid:68cb6fd6-6e92-4720-9407-7d3df47ecd41\”/><resource><Encounter xmlns=\”http://hl7.org/fhir\”><identifier><value value=\”urn:uuid:68cb6fd6-6e92-4720-9407-7d3df47ecd41\”/></identifier><status value=\”finished\”/><class value=\”outpatient\”/><type><text value=\”REG\”/></type><patient><reference value=\”https://mci.shrlive.dghs.gov.bd/api/v1/patients/98001095960\”/><display value=\”98001095960\”/></patient><participant><individual><reference value=\”https://dev.hris.survport.com/api/1.0/providers/20.json\”/></individual></participant><period><start value=\”2023-07-18T09:46:40.000+05:30\”/></period><serviceProvider><reference value=\”https://dev.hris.survport.com/api/1.0/facilities/10019842.json\”/></serviceProvider></Encounter></resource></entry></Bundle>”,

“healthId”: “98001095960”,

“id”: “bf5a744a-797e-4115-a065-6b6c09f19d89”,

“receivedAt”: “2023-07-18T09:47:03.027+0530”,

“updatedAt”: “2023-07-18T09:47:03.027+0530”

}

Response Codes :

412 – PRECONDITION_FAILED

400 – BAD_REQUEST

422 – UNPROCESSABLE_ENTITY

401 – UNAUTHORIZED

403 – FORBIDDEN

Basic Structure

A Composition resource will have

identifier – usually an unique id within the document
date – the date of editing the composition
status – the workflow status of the composition (final, preliminary etc) – usually final in our case.
subject – reference to the patient. This is the complete URL reference to the patient
encounter – references to the administrative encounter resource contained within the same document
List of sections – this are other FHIR resources that form the facts within the encounter. Usually these are internal references to the other entry resources in the same document.

The document will have references to existing and new resources. Existing resources include Patient, practitioner (provider) and some clinical resources like condition, medication & tests. In FHIR terms, we will have internal and external resource references in the document. See https://hl7.org/fhir/stu3/ for resource references.

Composition

Below is a sample example of FHIR Composition Resource. For detailed information of definition of composition (attributes), see here

Sample Composition

<Composition xmlns=“http://hl7.org/fhir”>

<identifier>

<value value=“urn:12fafd36-20f7-4f88-8721-9a4a31fbeacf”/>

</identifier>

<date value=“2023-01-07T12:00:15+05:30”/>

<status value=“final”/>

<subject>

<reference value=“https://mci.shrlive.dghs.gov.bd/api/v1/patients/98011725424″/>

<display value=“Rahima Begum”/>

</subject>

<encounter>

<reference value=“urn:07f02524-7647-43c1-a579-0c2c80f285ed”/>

<display value=“Encounter”/>

</encounter>

<section>

<content>

<reference value=“urn:40b43d8a-b582-4080-8c04-93697b82a795”/>

<display value=“Temperature”/>

</content>

</section>

<section>

<content>

<reference value=“urn:e45dbdca-4e39-4a79-b1b8-fd622fdff6e3”/>

<display value=“Diagnosis”/>

</content>

</section>

</Composition>

Encounter

Encounter happens between Practitioner/care-provider and a patient. The encounter snippet shown below is FHIR encounter, which captures the administrative information for workflow management. For SHR, the entire composition resource is the clinical “Encounter” the API serves.

Sample Encounter :

</identifier>

<type>

</type>

</subject>

</individual>

</participant>

</Encounter>

Where

class: classification – inpatient | outpatient | ambulatory | emergency | home | field | daytime | virtual
status: planned | in progress | onleave | finished | cancelled.
type: 0..*. Specifies type of encounter. e.g. consultation, surgical day-care, rehab etc. We will have to define a coded set for this. TBD.
participant: 0..*. Specifies care providers in this encounter. For example, in a surgery, there maybe multiple providers of different type.
serviceProvider: identifies the facility or community health clinic
identifier: local identifier in HMIS
subject – reference to the patient. This is the complete URL reference to the patient

NOTE: there are many other attributes of FHIR encounter (like hospitalization, location etc). They maybe included as we see use cases.

Important to note, how the encounter links with the composition resource described above. The composition resource above references the encounter resource within the same document using the same reference id.

Now, lets see how the temperate reading is recorded as “observation”, and diagnosis (influenza) as “condition”.

Observation

Observations are made for measurements and simple assertions made about a patient. Lets say, the patient’s temperature reading was recorded as 101 F.

</identifier>

<name>

</coding>

</name>

</subject>

</Observation>

Where:

identifier – is the unique id of this resource within the document.
name – describes what happened. This is a CodeableConcept. In the above example, it explains that “Temperature” was recorded. The system and the coding further uniquely identifies the concept in the Terminology Registry.
value[x] – result of the observation. It maybe – valueQuantity, valueString, valueDecimal, valueRation etc etc.
status – status of the observation. example – final, registered etc
subject – reference to the patient.

Again note, how the identifier of the above observation is used to link with the composition section.

Diagnosis

Diagnosis is captured through FHIR condition, with “category” as “Diagnosis“.

Sample Diagnosis:

<Condition xmlns=“http://hl7.org/fhir”>

<identifier>

<value value=“urn:e45dbdca-4e39-4a79-b1b8-fd622fdff6e3”/>

</identifier>

<subject>

<reference value=“http://mci.mcishr.dghs.gov.bd/api/v1/patients/98011725424″/>

<display value=“Rahima Begum”/>

</subject>

<encounter>

<reference value=“urn:07f02524-7647-43c1-a579-0c2c80f285ed”/>

<display value=“Encounter”/>

</encounter>

<asserter>

<reference value=“https://dev.hris.survport.com/api/1.0/providers/195854.json“/>

<display value=“Dr. Riaz”/>

</asserter>

<dateAsserted value=“2023-01-07T12:00:15+05:30”/>

<category>

<coding>

<system value=“http://hl7.org/fhir/condition-category”/>

<code value=“diagnosis”/>

<display value=“Diagnosis”/>

</coding>

</category>

<code>

<coding>

<system value=“https://tr.mcishr.dghs.gov.bd/openmrs/ws/rest/v1/tr/referenceterms/2218636a-0ef0-4fb1-ac7e-cf2a915b0ee4”/>

<code value=“J11.1”/>

<display value=“Influenza due to unidentified influenza virus with other respiratory manifestations”/>

</coding>

</code>

<status value=“provisional”/>

</Condition>

Where:

Condition.identifier – is the unique id of this resource within the document. Note, how the identifier is linked to the composition through the section identifier.
Condition.subject – the reference to the patient resource
Condition.encounter – reference to the encounter where the diagnosis was made. Note how it points to the encounter identifier in the same document.
Condition.asserter – the provider who asserted this condition
Condition.dateAsserted: Estimated or actual date the condition/problem/diagnosis was first detected/suspected.
Condition.code – identifies the condition, problem or diagnosis. In this case, the system is the URL reference where the code J11.1 can be found.
Condition.category: A category assigned to the condition. E.g. complaint | symptom | finding | diagnosis.
Condition.status: The clinical status of the Condition or diagnosis. Possible values – provisional, working, confirmed, refuted.
Condition.certainty: Non mandatory. But used in many diagnosis conditions.We probably need to define a coded concept like SNOMED for certainty. TBD
Condition.severity: Value set defines
- 399166001: Fatal
- 24484000: Severe
- 6736007: Moderate
- 255604002: Mild

Putting it all together

As explained above, all the resources in the example (encounter, observation, condition) are organized in the composition resource and bundling everything together to form the SHR “encounter” document.

<?xml version=”1.0″ encoding=”UTF-8″?>

<feed xmlns=”http://www.w3.org/2005/Atom”>

<title>Encounter</title>

<id>urn:73b7eb36-a1e2-4754-8518-19360c87ea62</id>

<updated>2023-01-07T12:00:15+05:30</updated>

<entry>

<title>Composition</title>

<id>urn:12fafd36-20f7-4f88-8721-9a4a31fbeacf</id>

<updated>2023-01-07T12:00:40.097+05:30</updated>

<author>

<name>OpenMRS</name>

</author>

<content type=”text/xml”>

<Composition xmlns=”http://hl7.org/fhir“>

<identifier>

<value value=”urn:12fafd36-20f7-4f88-8721-9a4a31fbeacf”/>

</identifier>

<date value=”2023-01-07T12:00:15+05:30″/>

<status value=”final”/>

<subject>

<reference value=”https://mci.shrlive.dghs.gov.bd/api/v1/patients/98011725424″/>

<display value=”Monika Ramesh”/>

</subject>

<encounter>

<reference value=”urn:07f02524-7647-43c1-a579-0c2c80f285ed”/>

<display value=”Encounter”/>

</encounter>

<section>

<content>

<reference value=”urn:40b43d8a-b582-4080-8c04-93697b82a795″/>

<display value=”Temperature”/>

</content>

</section>

<section>

<content>

<reference value=”urn:e45dbdca-4e39-4a79-b1b8-fd622fdff6e3″/>

<display value=”Diagnosis”/>

</content>

</section>

</Composition>

</content>

</entry>

<entry>

<title>Encounter</title>

<id>urn:07f02524-7647-43c1-a579-0c2c80f285ed</id>

<updated>2023-01-07T12:00:40.097+05:30</updated>

<author>

<name>bahmni</name>

</author>

<content type=”text/xml”>

<Encounter xmlns=”http://hl7.org/fhir”>

<identifier>

<value value=”urn:07f02524-7647-43c1-a579-0c2c80f285ed”/>

</identifier>

<status value=”finished”/>

<class value=”outpatient”/>

<type>

<text value=”outpatient”/>

</type>

<subject>

<reference value=”https://mci.shrlive.dghs.gov.bd/api/v1/patients/98011725424″/>

<display value=”Monika Ramesh”/>

</subject>

<participant>

<individual>

<reference value=”http://pr.twhosted.com/providers/18.json”/>

<display value=”Dr. Azad”/>

</individual>

</participant>

</Encounter>

</content>

</entry>

<entry>

<title>Temperature</title>

<id>urn:40b43d8a-b582-4080-8c04-93697b82a795</id>

<updated>2023-01-07T12:00:40.303+05:30</updated>

<author>

<name>bahmni</name>

</author>

<content type=”text/xml”>

<Observation xmlns=”http://hl7.org/fhir”>

<name>

<coding>

<system value=”https://tr.mcishr.dghs.gov.bd/openmrs/ws/rest/v1/tr/concepts/a1257651-7473-4c9b-bb0a-1244c5f3c09d”/>

<code value=”a1257651-7473-4c9b-bb0a-1244c5f3c09d”/>

<display value=”Temperature”/>

</coding>

</name>

<valueDecimal value=”97.0″/>

<status value=”final”/>

<reliability value=”ok”/>

<identifier>

<value value=”urn:40b43d8a-b582-4080-8c04-93697b82a795″/>

</identifier>

<subject>

<reference value=”https://mci.shrlive.dghs.gov.bd/api/v1/patients/98011725424″/>

<display value=”Monika Ramesh”/>

</subject>

</Observation>

</content>

</entry>

<entry>

<title>Diagnosis</title>

<id>urn:e45dbdca-4e39-4a79-b1b8-fd622fdff6e3</id>

<updated>2023-01-07T12:00:40.316+05:30</updated>

<author>

<name>bahmni</name>

</author>

<content type=”text/xml”>

<Condition xmlns=”http://hl7.org/fhir”>

<identifier>

<value value=”urn:e45dbdca-4e39-4a79-b1b8-fd622fdff6e3″/>

</identifier>

<subject>

<reference value=”https://mci.shrlive.dghs.gov.bd/api/v1/patients/98011725424″/>

<display value=”Monika Ramesh”/>

</subject>

<encounter>

<reference value=”urn:07f02524-7647-43c1-a579-0c2c80f285ed”/>

<display value=”Encounter”/>

</encounter>

<asserter>

<reference value=”https://dev.hris.survport.com/api/1.0/providers/18.json”/>

<display value=”Dr. Raiz”/>

</asserter>

<dateAsserted value=”2023-01-07T12:00:15+05:30″/>

<code>

<coding>

<system value=”https://tr.mcishr.dghs.gov.bd/openmrs/ws/rest/v1/tr/referenceterms/2218636a-0ef0-4fb1-ac7e-cf2a915b0ee4″/>

<code value=”J11.1″/>

<display value=”Influenza due to unidentified influenza virus with other respiratory manifestations”/>

</coding>

</code>

<category>

<coding>

<system value=”http://hl7.org/fhir/condition-category”/>

<code value=”diagnosis”/>

<display value=”Diagnosis”/>

</coding>

</category>

<status value=”provisional”/>

</Condition>

</content>

</entry>

</feed>

Synchronizing Terminology Database for FreeSHR

To ensure interoperability and consistency within the FreeSHR system, it’s crucial that client systems synchronize their terminology databases with the central server before constructing and submitting FHIR bundles. This document outlines the steps necessary for synchronizing terminologies and building a FHIR bundle with centralized terminologies.

Step-by-Step Process

Fetch Terminology Updates
- Initiate Synchronization: Start the synchronization process by sending a request to the central terminology server.
- Retrieve Terminologies: The central server will respond with the latest terminologies. Ensure that your client system can handle and store these updates.
- Update Local Database: Incorporate the retrieved terminologies into your local database. This may involve updating existing entries, adding new ones, or removing deprecated terminologies.
Implement Terminology Mapping (if required)
- Develop Mapping Service: If your client system uses localized terminologies, you may need to develop a mapping or translation service.
- Map Local to Central Terminologies: Ensure that all local terminologies can be accurately mapped to the central terminologies retrieved from the central server. This step is critical for maintaining consistency and ensuring that the data submitted to FreeSHR is interoperable.
- Maintain Mapping Accuracy: Regularly update your mapping service to reflect any changes in the central terminologies.
Construct the FHIR Bundle
- Utilize Central Terminologies: When constructing the FHIR bundle for a patient encounter, use the central terminologies directly or through your mapping service.
- Validate the Bundle: Ensure that the constructed FHIR bundle adheres to the FHIR standards and includes the correct terminologies. This validation step is essential for ensuring that the data can be accurately processed by FreeSHR.
Submit the FHIR Bundle
- Send to FreeSHR: Once the FHIR bundle is constructed and validated, submit it to the FreeSHR service for storing the encounter.
- Handle Response: Process the response from FreeSHR to confirm successful submission or handle any errors that may occur.

Best Practices

Regular Synchronization: Schedule regular synchronization intervals to ensure your local database is always up-to-date with the latest terminologies.
Error Handling: Implement robust error handling mechanisms to manage any issues that arise during synchronization or submission.
Performance Optimization: Optimize your terminology synchronization and mapping processes to minimize latency and ensure efficient operation.
Documentation: Maintain comprehensive documentation of your synchronization and mapping processes to facilitate maintenance and troubleshooting.

By following these steps, client systems can ensure that they are using the most up-to-date and accurate terminologies, thereby maintaining interoperability and consistency within the FreeSHR ecosystem.

Integration with the Terminology Registry

Introduction

The Terminology Registry is a software tool that allows authorized personnel to manage the medical terminology dictionary used in clinical practice. Authorized users can add new terms or modify existing ones. The Terminology Registry is designed to publish these changes to client systems online immediately.

The Terminology Registry server is built using OpenMRS, utilizing OpenMRS’ concept dictionary to manage clinical terms.

Publishing Changes

The Terminology Registry server uses Atom Feeds to publish changes. Each change to a term results in a new event in the feed, which includes meta-information such as the author, ID, and the last updated time. The feed document contains a list of entries for each event, such as adding or modifying a term, in the order they occurred. Each entry includes a URL that points to the updated entity on the Terminology Registry server. This URL returns the entire entity, not just the changed fields, so the consumer must handle the logic to determine the changes and merge them.

Example Feed

Below is an example of an Atom Feed from the Terminology Registry:

<?xml version=”1.0″ encoding=”UTF-8″?>

<title>Patient AOP</title>

<name>OpenMRS</name>

</author>

<generator uri=”https://github.com/ICT4H/atomfeed”>OpenMRS Feed Publisher</generator>

<entry>

<title>Diagnosis</title>

<id>tag:atomfeed.ict4h.org:83898e4e-05d9-4f37-a530-8f753035234b</id>

<![CDATA[/openmrs/ws/rest/v1/concept/aa21a8a6-7903-4d5e-af05-c1caae1abbf5?v=custom:(uuid,description,name:(uuid,name,locale,conceptNameType),datatype,set,version,retired,names,answers,setMembers,mappings:(uuid,conceptReferenceTerm,conceptMapType))]]>

</content>

</entry>

</feed>

Feed URLs

The Terminology Registry server publishes feeds for all concepts and for specific types of concepts (one feed per concept class). Related entities like concept reference terms also have their own feeds. Below is a list of URLs for the feeds published by the Terminology Registry server:

/openmrs/ws/atomfeed/concept/recent – Publishes events related to all concepts.

/openmrs/ws/atomfeed/diagnosis/recent – Publishes events related to all diagnoses.

/openmrs/ws/atomfeed/conceptreferenceterm/recent – Publishes events related to all concept reference terms.

Concept Reference Term API

Introduction

The Concept Reference Term API allows for managing and interacting with medical terminologies. It is a part of the Terminology Registry server, which is implemented using OpenMRS.

Atom Feed

The feed for concept reference terms is available at: http://host_name_for_tr/openmrs/ws/atomfeed/conceptreferenceterm/recent. The feed contains events for term changes and includes URLs for fetching the complete updated entity.

Data Structure

The URL format for fetching a concept reference term is: /openmrs/ws/rest/v1/conceptreferenceterm/<uuid>?v=custom:(fields). A sample XML response includes fields like uuid, name, description, code, and version.

Field Description

uuid: Unique identifier for the concept reference term.
name: Human-readable name.
description: Detailed description.
code: Unique code in the coding system.
version: Current version.
retired: Retirement status.
conceptSource: Source or namespace.
conceptReferenceTermMaps: Related terms and their mappings.
links: Related entities and their URIs.
resourceVersion: API version.

For more detailed information, refer to the full documentation on the Concept Reference Term API.

Terminology APIs

Introduction

The Terminology APIs are designed to manage and interact with medical terminologies, classified into Reference Terminologies and Interface Terminologies. Reference Terminologies ensure semantic interoperability and are maintained by recognized authorities. Interface Terminologies are used at points-of-care and are mapped to standardized codes.

Atom Feeds

The Terminology Server publishes several feeds:

Reference Terms Feed: /openmrs/ws/atomfeed/conceptreferenceterm/recent

Concepts Feed: /openmrs/ws/atomfeed/concept/recent

Medications Feed: /openmrs/ws/atomfeed/medication/recent

Category-specific Feeds: For example, /openmrs/ws/atomfeed/diagnosis/recent for diagnosis.

For more details, refer to the Terminology APIs documentation.

Introduction of New Terminologies

When introducing a new terminology into the Terminology Registry (TR), consider whether it should be centrally defined for use across the entire Health Information Exchange (HIE) ecosystem.

Steps for Adding a New Terminology:

Determine Scope: If the terminology is specific to one hospital, it can remain local. If applicable to multiple hospitals, it should be added to the TR.
Centralization: Concepts related to tests, procedures, diagnoses, and orders must go into the TR. Consult with the TR group to ensure no duplicates.
Use TR Concept Proposal Module: This module should be used for creating new concepts.

For detailed guidelines and decision-making processes, consult with the Terminology Advisory Group (TWG) and refer to the detailed documentation.

Overview of SHR Development

Steps for Pushing Data from a Hospital to Central HIE

Detailed Integration Steps

API Endpoints:

Save an encounter.

Get a specific encounter for a patient:

Basic Structure

Composition

Encounter

Observation

Diagnosis

Putting it all together

Synchronizing Terminology Database for FreeSHR

Step-by-Step Process

Best Practices

Integration with the Terminology Registry

Introduction

Publishing Changes

Example Feed

Feed URLs

Concept Reference Term API

Introduction

Atom Feed

Data Structure

Field Description

Terminology APIs

Introduction

Atom Feeds

Introduction of New Terminologies

Steps for Adding a New Terminology:

Contact Us

Important Links

Policies

Follow Us

Clinical Data Exchange-Tech

Overview of SHR Development

Steps for Pushing Data from a Hospital to Central HIE

Detailed Integration Steps

API Endpoints:

Save an encounter.

Get a specific encounter for a patient:

Basic Structure

Composition

Encounter

Observation

Diagnosis

Putting it all together

Synchronizing Terminology Database for FreeSHR

Step-by-Step Process

Best Practices

Integration with the Terminology Registry

Introduction

Publishing Changes

Example Feed

Feed URLs

Concept Reference Term API

Introduction

Atom Feed

Data Structure

Field Description

Terminology APIs

Introduction

Atom Feeds

Introduction of New Terminologies

Steps for Adding a New Terminology:

Contact Us

Important Links

Policies

Follow Us

AI Assistant of MIS, DGHS