Page Comparison

1. Format

The API is based on REST convention and would uses HL7 FHIR for exchange of data.

2. 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). Refer the Identity Provider page for more information on how to use the Identity Provider APIs. 

API

Save an encounter.

POST  /patients/{health Id}/encounters

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

<Bundle xmlns="http://hl7.org/fhir">
	<id value="c820e3ea-d7a4-489a-9284-fbaaf0fe8e1a"/>
	<meta>
		<lastUpdated value="2017-03-14T11:39:10.000+05:30"/>
	</meta>
	<type value="collection"/>
	<entry>
		<fullUrl value="urn:uuid:d1624f29-6962-4d15-9931-09dd5c85b9cf"/>
		<resource>
			<Composition xmlns="http://hl7.org/fhir">
				<identifier>
					<value value="urn:uuid:d1624f29-6962-4d15-9931-09dd5c85b9cf"/>
				</identifier>
				<date value="2017-03-14T11:39:10.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="http://mci.twhosted.com/api/default/patients/98001098063"/>
					<display value="98001098063"/>
				</subject>
				<author>
					<reference value="http://fr.twhosted.com/api/1.0/facilities/10019842.json"/>
				</author>
				<encounter>
					<reference value="urn:uuid:14278c1c-95b4-43f0-aa35-66e366fb45dc"/>
				</encounter>
				<section>
					<entry>
						<reference value="urn:uuid:14278c1c-95b4-43f0-aa35-66e366fb45dc"/>
						<display value="Encounter"/>
					</entry>
				</section>
			</Composition>
		</resource>
	</entry>
	<entry>
		<fullUrl value="urn:uuid:14278c1c-95b4-43f0-aa35-66e366fb45dc"/>
		<resource>
			<Encounter xmlns="http://hl7.org/fhir">
				<identifier>
					<value value="urn:uuid:14278c1c-95b4-43f0-aa35-66e366fb45dc"/>
				</identifier>
				<status value="finished"/>
				<class value="field"/>
				<type>
					<text value="REG"/>
				</type>
				<patient>
					<reference value="http://mci.twhosted.com/api/default/patients/98001098063"/>
					<display value="98001098063"/>
				</patient>
				<participant>
					<individual>
						<reference value="http://pr.twhosted.com/api/1.0/providers/20.json"/>
					</individual>
				</participant>
				<period>
					<start value="2017-03-14T11:38:52.000+05:30"/>
				</period>
				<serviceProvider>
					<reference value="http://fr.twhosted.com/api/1.0/facilities/10019842.json"/>
				</serviceProvider>
			</Encounter>
		</resource>
	</entry>
</Bundle>

{
    "encounterId": "9f81a363-ede1-4bd0-8af2-eb73045c9ab1",
    "errors": [],
    "successful": true,
    "errorResult": null
}

{
    "httpStatus": "422",
    "message": "Unprocessable entity : [{"field":"f:Encounter/f:patient","type":"invalid","reason":"http://mci.twhosted.com/api/default/patients/9801098063:Patient Health Id does not match."}]",
    "errors": [
        {
            "field": "f:Encounter/f:patient",
            "type": "invalid",
            "reason": "http://mci.twhosted.com/api/default/patients/9801098063:Patient's Health Id does not match."
        }
    ]
}

Update an encounter

PUT  /patients/{health Id}/encounters/{encounter_id}

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

<Bundle xmlns="http://hl7.org/fhir">
	<id value="c820e3ea-d7a4-489a-9284-fbaaf0fe8e1a"/>
	<meta>
		<lastUpdated value="2017-03-14T11:39:10.000+05:30"/>
	</meta>
	<type value="collection"/>
	<entry>
		<fullUrl value="urn:uuid:d1624f29-6962-4d15-9931-09dd5c85b9cf"/>
		<resource>
			<Composition xmlns="http://hl7.org/fhir">
				<identifier>
					<value value="urn:uuid:d1624f29-6962-4d15-9931-09dd5c85b9cf"/>
				</identifier>
				<date value="2017-03-14T11:39:10.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="http://mci.twhosted.com/api/default/patients/98001098063"/>
					<display value="98001098063"/>
				</subject>
				<author>
					<reference value="http://fr.twhosted.com/api/1.0/facilities/10019842.json"/>
				</author>
				<encounter>
					<reference value="urn:uuid:14278c1c-95b4-43f0-aa35-66e366fb45dc"/>
				</encounter>
				<section>
					<entry>
						<reference value="urn:uuid:14278c1c-95b4-43f0-aa35-66e366fb45dc"/>
						<display value="Encounter"/>
					</entry>
				</section>
			</Composition>
		</resource>
	</entry>
	<entry>
		<fullUrl value="urn:uuid:14278c1c-95b4-43f0-aa35-66e366fb45dc"/>
		<resource>
			<Encounter xmlns="http://hl7.org/fhir">
				<identifier>
					<value value="urn:uuid:14278c1c-95b4-43f0-aa35-66e366fb45dc"/>
				</identifier>
				<status value="finished"/>
				<class value="field"/>
				<type>
					<text value="REG"/>
				</type>
				<patient>
					<reference value="http://mci.twhosted.com/api/

default/patients/

98001098063"/>

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".

<Condition xmlns="http://hl7.org/fhir">
   <identifier>
     <value value="urn:e45dbdca-4e39-4a79-b1b8-fd622fdff6e3"/>
   </identifier>
   <subject>
     <reference value="http://mci.twhosted.com/api/v1/patients/5893922485019082753"/>
     <display value="Monika Ramesh"/>
   </subject>
   <encounter>
     <reference value="urn:07f02524-7647-43c1-a579-0c2c80f285ed"/>
     <display value="Encounter"/>
   </encounter>
   <asserter>
     <reference value="http://pr.twhosted.com/providers/18.json"/>
     <display value="Dr. Azad"/>
   </asserter>
   <dateAsserted value="2015-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="http://tr.twhosted.com/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
   
• Condition.onset[x] - can be "onsetDate" or "onsetAge" : Estimated or actual date when the condition began.
  

NOTE: This definition of the "condition" is meant to be minimal set of definitions seen at a point of time, and maybe expanded if needed.

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>2015-01-07T12:00:15+05:30</updated>
 <entry>
   <title>Composition</title>
   <id>urn:12fafd36-20f7-4f88-8721-9a4a31fbeacf</id>
   <updated>2015-01-07T12:00:40.097+05:30</updated>
   <author>
     <name>OpenMRS</name>
   </author>
   <content type="text/xml">

					<display value="98001098063"/>
				</patient>
				<participant>
					<individual>
						<reference value="http://pr.twhosted.com/api/1.0/providers/20.json"/>
					</individual>
				</participant>
				<period>
					<start value="2017-03-14T11:38:52.000+05:30"/>
				</period>
				<serviceProvider>
					<reference value="http://fr.twhosted.com/api/1.0/facilities/10019842.json"/>
				</serviceProvider>
			</Encounter>
		</resource>
	</entry>
</Bundle>

{
    "encounterId": "9f81a363-ede1-4bd0-8af2-eb73045c9ab1",
    "errors": [],
    "successful": true,
    "errorResult": null
}

{
    "httpStatus": "422",
    "message": "Unprocessable entity : [{"field":"f:Encounter/f:patient","type":"invalid","reason":"http://mci.twhosted.com/api/default/patients/9801098063:Patient Health Id does not match."}]",
    "errors": [
        {
            "field": "f:Encounter/f:patient",
            "type": "invalid",
            "reason": "http://mci.twhosted.com/api/default/patients/9801098063:Patient's Health Id does not match."
        }
    ]
}

Get all encounters for a patient.

1. Format

The API is based on REST convention and would uses HL7 FHIR for exchange of data.

2. 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). Refer the Identity Provider page for more information on how to use the Identity Provider APIs. 

API

POST  /patients/{health Id}/encounters

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) OR application/atom+xml

<?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="http://shr-qa.twhosted.com/patients/98001095960/encounters" />
    <link rel="via" type="application/atom+xml" href="http://shr-qa.twhosted.com/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>2016-07-18T04:17:03Z</updated>
    <entry>
        <title>Encounter:bf5a744a-797e-4115-a065-6b6c09f19d89</title>
        <link rel="via" type="application/xml" href="/patients/98001095960/encounters/bf5a744a-797e-4115-a065-6b6c09f19d89" />
        <category term="encounter" />
        <category term="encounter_updated_at:2016-07-18T09:47:03.027+0530" />
        <id>7ace6830-4c9e-11e6-b8ee-ea409bb33e8c</id>
        <updated>2016-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="2016-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>

><identifier><value value="urn:uuid:

ac5c9949-

d46d-

4138-

9966-

356dab31520a"/></

       </identifier>

identifier><date value="2016-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"/

       <subject>

><confidentiality value="N"/><subject><reference value="http://mci.twhosted.com/api/

          <display value="Monika Ramesh"/>

       </subject>

       <encounter>

default/patients/98001095960"/><display value="98001095960"/></subject><author><reference value="http://fr.twohosted.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"

       </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 

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

           <display value="Temperature"/>

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.twhosted.com/api/default/patients/98001095960"/><display value="98001095960"/></patient><participant><individual><reference value="http://pr.twhosted.com/api/1.0/providers/20.json"/></individual></participant><period><start value="2016-07-18T09:46:40.000+05:30"/></period><serviceProvider><reference value="http://fr.twohosted.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" />

       </section>

<category term="encounter_updated_at:2016-07-18T09:49:02.444+0530" />
    

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

<updated>2016-

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="2016-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="2016-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="http://mci.twhosted.com/api/

default/patients/

98001095960"/

><display value="

98001095960"/

></subject><author><reference value="http:/

/fr.twohosted.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.twhosted.com/api/default/patients/98001095960"/><display value="98001095960"/></patient><participant><individual><reference value="http://pr.twhosted.com/api/1.0/providers/20.json"/></individual></participant><period><start value="2016-07-18T09:46:40.000+05:30"/></period><serviceProvider><reference value="http://

fr.

twohosted.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="

2016-07-18T00:00:00.000+05:30"/><vaccineCode><coding><system value="http://

172.18.

46.56:9080/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="http://

mci.twhosted

.com/api/default/patients/98001095960"/><display value="

98001095960"

/></patient><wasNotGiven value="

false"/><reported value="true"/><requester><reference value="http://pr.twhosted.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. 

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

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-TypeAccept: application/xml;charset=utf-8

Body (example) :

xml

{
    "content": "<Bundle xmlns=\"http://hl7.org/fhir\"

><id value=\"

0ccde14f-

0047-

4e9a-

98bd-

71f81991f6c2\"/

><meta><lastUpdated value=\"

2016-

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=\"

2016-

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=\"http://mci.twhosted.com/api/default/patients/

98001095960\"/

><display value=\"

98001095960\"/

></subject><author><reference value=\"http://fr.twhosted.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.twhosted.com/api/default/patients/

98001095960\"/

><display value=\"

98001095960\"/

></patient><participant><individual><reference value=\"http://pr.twhosted.com/api/1.0/providers/20.json\"/

></individual></participant><period><start value=\"2016-07-18T09:46:40.000+05:30\"/

></period><serviceProvider><reference value=\"http://fr.twhosted.com/api/1.0/facilities/10019842.json\"/

get all encounters for a patient.

    GET /patients/{health Id}/encounters

         headers

></serviceProvider></Encounter></resource></entry></Bundle>",
    "healthId": "98001095960",
    "id": "bf5a744a-797e-4115-a065-6b6c09f19d89",
    

get a specific encounter for a patient. 

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

           headers

        Accept: application/xml

"receivedAt": "2016-07-18T09:47:03.027+0530",
    "updatedAt": "2016-07-18T09:47:03.027+0530"
}

Get all encounters for a catchment

     GET /catchments/{catchment code}/encounters

     headers

   headers

     Accept: application/atom+xml

For more details, please refer Catchment Encounters API

Context

Shared Health Record (SHR) serves as a repository containing clinical care information for patients. SHR houses subset of data from various EMRs from different care delivery organisations. This record is shared between different institutions and systems. For patients, such information are represented as Encounters in SHR. Each such encounter information therein is stored as a FHIR resource document.

 FHIR encounter – is a resource that mainly has administrative information, for example contact with patient with date, participants etc. Whereas in medical domain, encounter is more holistic, that includes clinical information gathered for patients, drugs/tests advised, observations/diagnoses done etc.

Lets take an example of an outpatient consultation of a doctor with a patient where the patient is diagnosed with presumed “Influenza”, and doctor also noted down (after physical examination) her temperature readings.

The EMR sytsem at the Facility would communicate all the facts with SHR by means of a “document”, formed to provide coherent context for  an “Encounter” information. The context description of an encounter can be modeled using a FHIR resource "Bundle".

In our context, this "bundle" is basically a collection of other FHIR resources.  The most important resource within the bundle is “Composition”, that organizes/bundles other resources relevant to the clinical encounter within the document. Following is the basic structure

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 here for resource references.

Composition

For detailed information of definition of composition (attributes), see here

<Composition xmlns="http://hl7.org/fhir">
   <identifier>
     <value value="urn:12fafd36-20f7-4f88-8721-9a4a31fbeacf"/>
   </identifier>
   <date value="2015-01-07T12:00:15+05:30"/>
   <status value="final"/>
   <subject>
     <reference value="http://mci.twhosted.com/api/v1/patients/5893922485019082753"/>
     <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>

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.

<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="http://mci.twhosted.com/api/v1/patients/5893922485019082753"/>
      <display value="Monika Ramesh"/>
   </subject>
   <participant>
      <individual>
        <reference value="http://pr.twhosted.com/providers/18.json"/>
        <display value="Dr. Azad"/>
      </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.

<Observation xmlns="http://hl7.org/fhir">
   <identifier>
      <value value="urn:40b43d8a-b582-4080-8c04-93697b82a795"/>
   </identifier>
   <name>
      <coding>
        <system value="http://tr.twhosted.com/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="101.0"/>
   <status value="final"/>
   <reliability value="ok"/>
   <subject>
      <reference value="http://mci.twhosted.com/api/v1/patients/5893922485019082753"/>
      <display value="Monika Ramesh"/>
   </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".

<Condition xmlns="http://hl7.org/fhir">
   <identifier>
     <value value="urn:e45dbdca-4e39-4a79-b1b8-fd622fdff6e3"/>
   </identifier>
   <subject>
     <reference value="http://mci.twhosted.com/api/v1/patients/5893922485019082753"/>
     <display value="Monika Ramesh"/>
   </subject>
   <encounter>
     <reference value="urn:07f02524-7647-43c1-a579-0c2c80f285ed"/>
     <display value="Encounter"/>
   </encounter>
   <asserter>
     <reference value="http://pr.twhosted.com/providers/18.json"/>
     <display value="Dr. Azad"/>
   </asserter>
   <dateAsserted value="2015-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="http://tr.twhosted.com/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
   
• Condition.onset[x] - can be "onsetDate" or "onsetAge" : Estimated or actual date when the condition began.
  

NOTE: This definition of the "condition" is meant to be minimal set of definitions seen at a point of time, and maybe expanded if needed.

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>2015-01-07T12:00:15+05:30</updated>
 <entry>
   <title>Composition</title>
   <id>urn:12fafd36-20f7-4f88-8721-9a4a31fbeacf</id>
   <updated>2015-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="2015-01-07T12:00:15+05:30"/>

       <status value="final"/>

       <subject>

          <reference value="http://mci.twhosted.com/api/v1/patients/5893922485019082753"/>

          <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>2015-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="http://mci.twhosted.com/api/v1/patients/5893922485019082753"/>
         <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>2015-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="http://tr.twhosted.com/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="http://mci.twhosted.com/api/v1/patients/5893922485019082753"/>
 <display value="Monika Ramesh"/>
 </subject>
 </Observation>
 </content>
 </entry>
 <entry>
 <title>Diagnosis</title>
 <id>urn:e45dbdca-4e39-4a79-b1b8-fd622fdff6e3</id>
 <updated>2015-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="http://mci.twhosted.com/api/v1/patients/5893922485019082753"/>
 <display value="Monika Ramesh"/>
 </subject>
 <encounter>
 <reference value="urn:07f02524-7647-43c1-a579-0c2c80f285ed"/>
 <display value="Encounter"/>
 </encounter>
 <asserter>
 <reference value="http://pr.twhosted.com/providers/18.json"/>
 <display value="Dr. Azad"/>
 </asserter>
 <dateAsserted value="2015-01-07T12:00:15+05:30"/>
 <code>
 <coding>
 <system value="http://tr.twhosted.com/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>F
 </feed>