Learn

Explore development tutorials, how-tos and case studies

Categories

Key Words

Playing with FHIR – TUT002 : Creating a PATIENT Resource

For this tutorial we are going to go through the process of “creating”  resources on a FHIR based system. FHIR has a RESTful interface mechanism and uses the standard HTTP verbs to achieve this.

Further details on the FHIR RESTful specification are available on the FHIR website

For the purposes of this tutorial we will work with the Patient resource from FHIR. This resource can carry a rich set of information but we’ll just create a minimal patient during this tutorial. The XML below shows an example patient instance that can be used.

<?xml version="1.0" encoding="UTF-8"?>
<Patient xmlns="http://hl7.org/fhir">
    <identifier>
        <system value="http://www.nhsdev.net/psn"/>
        <value value="{{id}}"/>
    </identifier>
    <active value="true"/>
    <name>
        <use value="official"/>
        <family value="{{familyName}}"/>
        <given value="{{givenName}}"/>
    </name>
    <gender value="{{gender}}"/>
    <birthDate value="{{dob}}"/>
    <managingOrganization>
        <reference value="Organization/NHSDEVORG"/>
    </managingOrganization>
</Patient>

So for the first stage of this tutorial you will need to get the XML ready to create your patient.

  • Copy the XML above into a text editor and make the following edits
  • Amend {{id}} to be your fictitious patient number (it’s up to you but a suggest a 6 or 7 digit random number)
  • Amend {{familyName}} to be the “Surname” of your patient
  • Amend {{givenName}} to be the “Forename” of your patient
  • Amend {{gender}} to be the gender – “male” or “female”
  • Amend {{dob}} to be the date of birth in the format YYYY-MM-DD  (e.g. 2016-11-13 )

You should now be ready to create your patient. For this we will use the Postman tool as per Tutorial 001.

For this tutorial we will use a public FHIR server with an endpoint of  http://fhir2.healthintersections.com.au/open/ .Note this is a public server as such there are no guarantees of its availability or performance – though it usually very good.

So open up Postman to get a screen along the lines of the following:

TUT002-01

So to create a record via REST we need to perform a “POST” against the endpoint. To do this ensure that:

  • The HTTP Verb (top left corner) need to be set to “POST”
  • The URL need to be set to the FHIR endpoint for Patients – http://fhir2.healthintersections.com.au/open/Patient
  • The option to view the “Body” of the HTTP post need to be selected
  • The “raw” option (directly below Body) also needs to be selected. You now will have a large text box into which you insert the data to be “POSTed”
  • Insert your XML file into the text box
  • Press the “Send”  button

TUT002-02

Assuming everything has gone well you should now see the following :

  • Below the text box where you entered your XML you should see a response “Status 201 Created”. This is stating that a HTTP Response code of 201 has been returned. This denotes a successful record creation.
  • The new text box at the bottom of the screen now hold a copy of what has been created, this will look very much like the XML you sent in with the exception that there are some extra elements.
<?xml version="1.0" encoding="UTF-8"?>
<Patient xmlns="http://hl7.org/fhir">
    <id value="436"/>
    <meta>
        <versionId value="1"/>
        <lastUpdated value="2015-11-13T14:26:50Z"/>
    </meta>
    <identifier>
        <system value="http://www.nhsdev.net/psn"/>
        <value value="4568532"/>
    </identifier>
    <active value="true"/>
    <name>
        <use value="official"/>
        <family value="Vanilla"/>
        <given value="Vincent"/>
    </name>
    <gender value="male"/>
    <birthDate value="1989-01-21"/>
    <managingOrganization>
        <reference value="Organization/NHSDEVORG"/>
    </managingOrganization>
</Patient>

The additional elements added are :

Patient.id  – this is the local identifier of this resource on the FHIR server, in my case this is 436 it has been allocated by the server  (Note this is not the business identifier of the Patient). In later tutorials we will learn how we can allocate the number ourselves.
Patient.meta.versionId – the version of the FHIR resource. Note this does not have to be an incrementing number, or even a number at all.
Patient.meta.lastUpdated – a timestamp of when the resource was last updated, or in this case created.

So now we have created the resource we will demonstrate how we can retrieve it again based on the fact that we know its logical identifier. The url we need to use is http://fhir2.healthintersections.com.au/open/Patient/436. To read a resource using REST we need to use the GET verb.

Using Postman once again we get the following.

TUT002-04

The status code returned in “200 OK” which means the GET of Patient resource with an id of 436 was successful.

That’s it for this tutorial. In the next tutorial we’ll focus on different ways of retrieving resources using searches.

If you have any questions or feedback on this tutorial then please feedback so we can improve the future tutorials.