Make your first FHIR client – within one hour!

By Rob Mulders – During the May 2015 FHIR connectathon in Paris, somebody asked me how much time it would take him to make his first FHIR client application. It inspired me to write a sort of Hello World program and see how much time it would take me. You have to know that I haven’t been programming for many years. The last time was about 12 years ago in Delphi. And before that I used to code in FoxPro 2.6 for DOS.

In this blog I would like to share with you the steps needed to create a very simple FHIR client. First, the client connects to a FHIR server on the internet. After that, the client fetches all patients from the server having “Rob” in the name, to show them in a form.

Step 1 – Create a project

This step assumes you have Visual Studio ready on your machine. I used Visual Studio 2012 Professional. Fire up Visual Studio without any old project open. Choose File – New – Project from the menu. In the dialog box, choose Visual C# – Windows – Windows Form Application. In the Name field, enter the name you want to have for your first program. Then click OK. Visual Studio creates a solution with a form called Form1. Press F5 or click on Start to run and test your program. If everything is ok, you will see the following screen:

MyFirstFhirProject-Img1

Step 2 – Get the .NET API for connecting to FHIR servers

Since your program wants to connect to a FHIR server without doing complex stuff yourself, you will need the .Net API that is provided by my colleagues at Furore. On the menu, choose Project – Manage NuGet Packages. A dialog box will appear. In the upper right corner, type FHIR in the search box. A list of about six APIs will appear. Make sure you choose HL7 FHIR Core support API for DSTU2. Then click on Install. If everything is ok, a green marker will appear. If not, I don’t know what to do :-). The NuGet manager will automatically include the JSON.net package for you, since the FHIR API is dependent on that one. Close the dialog box and run your program again to verify it still works.

Step 3 – Searching patients on a FHIR server

I chose to use a button to start the connection to a FHIR-server. On the menu click View – Toolbox and search for button. Click on Button and drag a button on your form. Widen the button a bit to be able to display some text in it. Then double click on your own button. You will come to a piece of code called button1_Click. In this function, copy a few lines of code from the box below into your click function. You should have your function as follows:

private void button1_Click(object sender, EventArgs e)
{   
   var endpoint = new Uri("http://spark.furore.com/fhir");
   var client = new FhirClient(endpoint);

   var query = new string[] { "name=Rob" };
   var bundle = client.Search("Patient", query);

   button1.Text = "Got " + bundle.Entry.Count() + " records!";
}

Now run your program. You will get an error while compiling! Visual Studio says “The type or namespace FhirClient could not be found”. What we have to do is include the FHIR API classes in our code module, by typing three lines of code in the top part. In your source code, scroll up and add three using statements below the others:

using Hl7.Fhir;
using Hl7.Fhir.Rest;
using Hl7.Fhir.Model;

Run your program again. This time, it rolls without compile errors. Click on your own button. If everything goes right, you should see the form like this:

MyFirstFhirProject-Img2

Step 4 – Displaying patient information from a FHIR bundle

In your code, you have created a variable called bundle. A bundle is the FHIR way to have a collection of data. Actually, the bundle not only knows how much records it got from the FHIR server, it also contains the data itself. So, to display the patients, we need to display the data from the bundle onto the form.

First, add a label to your form to display information in. On the menu click View – Toolbox and search for label. Click on Label and drag a label on your form. Click on your form to activate it. Put the label a bit to the left under your button to make space for showing a list.

Now, go to your code and add some lines below your last line of code. In total, the function should look like this:

private void button1_Click(object sender, EventArgs e)
{
   var endpoint = new Uri("http://spark.furore.com/fhir");
   var client = new FhirClient(endpoint);

   var query = new string[] { "name=Rob" };
   var bundle = client.Search("Patient", query);

   button1.Text = "Got " + bundle.Entry.Count() + " records!";

   label1.Text = "";
   foreach (var entry in bundle.Entry)
   {
      Patient p = (Patient)entry.Resource;
      label1.Text = label1.Text + p.Id + " " + p.Name.First().Text + "\r\n";   
   }
}

If you run your program, you will get output like this:

MyFirstFhirProject-Img3

Congratulations! You just made your first FHIR client showing patients from a FHIR server.

Finally

I will end with some words about the FHIR resource Patient though. You can see there is no “Rob” in any of the names in my output form. But didn’t we search on that? Yes, we did.

You have to know a Patient in FHIR has a complex structure for names. Name consists of an array of HumanNames. The function Name.First() in the code is not about someone’s first name, something I thought at first. It returns the first HumanName that meets a condition. But since I didn’t specify a condition to First(), we simply get the first HumanName of the list. HumanName is a combination of different fields: family, given, prefix and suffix. Once you have a HumanName, you can use the .Text property to make a decent name from the four fields involved. So, even though there is no “Rob” in the visible list in the form, there apparently are multiple HumanNames attached to the eight patients found. For each patient there is at least one HumanName with “Rob” in it. And that could also be the family name “Roberts”.

Please feel free to contact me at r.mulders@furore.com with any questions.

Have fun with FHIR!

/Rob.

Advertisements

21 thoughts on “Make your first FHIR client – within one hour!

  1. Pingback: Creating simple FHIR clients | Hay on FHIR

  2. Steve Yetter

    I get an exception when I try to run this in VS 2013 professional. Did I load the wrong core library?
    An unhandled exception of type ‘System.FormatException’ occurred in Hl7.Fhir.Core.dll

    Additional information: Cannot parse xml: For security reasons DTD is prohibited in this XML document. To enable DTD processing set the DtdProcessing property on XmlReaderSettings to Parse and pass the settings into XmlReader.Create method.

    Reply
    1. muldersrob Post author

      Hi Steve,
      I had the same kind of error while using the DSTU1 FHIR API, instead of the newest DSTU2 one. You can check this in the Package Manager of VS.
      Kind regards,
      Rob.

      Reply
    1. muldersrob Post author

      Thanks Matt. You are right. Must have happened while I transferred the code from VS to WordPress. In my source, the last parens is not there. Will try to correct the blog post also.

      Reply
  3. geekmaniac

    This is little off topic, but I would like to ask, how can I parse & get a value for an extension(Hl7.Fhir.Model.Extension) in a FHIR resource using FHIR Core library for .NET?

    Reply
    1. Marten Smits

      Hi geekmaniac,

      There are a couple of ways you can get to the value of an extension:

      1. Works with every extension:
      fhirelement.GetExtensionValue<type>(url)
      where fhirelement can be the resource itself or every element within a resource, Type is a Fhir type (string, code, boolean, etc.), and url is the URL of the extension.

      2. There are some shortcuts for simple extensions:
      fhirelement.GetBoolExtension(url) will get you the value of an extension when it’s a boolean.
      fhirelement.GetStringExtension(url) will get you the value of an extension when it’s a string.

      I hope this is clear, if it isn’t or if you have any other questions, you can contact me or reply to this post.

      Reply
  4. Venkat

    I am getting this error:
    ‘Hl7.Fhir.Model.Bundle’ does not contain a definition for ‘Entry’ and no extension method ‘Entry’ accepting a first argument of type ‘Hl7.Fhir.Model.Bundle’ could be found (are you missing a using directive or an assembly reference?) followed all above steps, but using VS2013Pro.

    Reply
    1. mirjambaltus

      Hello Venkat,

      this problem occurs when you have installed the NuGet package for HL7 Fhir DSTU1, since the code is written for DSTU2. Please uninstall this package and add the package called HL7 FHIR Core support API for DSTU2.

      Please contact me if you still have the problem after changing the package.

      Reply
  5. Raoof

    Hi Mr. Ewout Kramer,

    I use the fhir nuget package in my c# application. The library has been very much helpful for creating the fhir service in DSTU2. I have just got a question – is there a way in the library to validate the patient resource against the dafpatient profile?

    Regards,

    Reply
  6. Pingback: A Student at the 2015 FHIR DevDays Student Track | The Fhirplace

  7. Aeyoss Antelope

    I am not sure if anyone cares about this now, but…

    The query “Rob” shown in the code returns an empty bundle. Query “R” gives 8 bundle entries and query “p” gives 20 bundle entries.

    I discovered this by trial-and-error.

    HTH.

    Reply
  8. DimSouls

    Hello, i don’t know if anyone is responding here,but i want to ask 2 questions if someone can help me.
    1) Is there any documentation for the patient data {i want to see a guide for commands like this p.Name.First().Family.FirstOrDefault() }
    2) The data that the servers sends can i save them in an .xml file ?

    Reply
    1. Mirjam Baltus

      Hi!
      1) You can look at the definition of the Patient resource in the specification: http://www.hl7.org/fhir/patient.html. For each of the 0..* fields in the resource, there will be a .Net List in the model in the FHIR API. The First() and FirstOrDefault() constructions are just standard .Net methods to work with lists.
      2) The FHIR API offers methods for serialization to create a valid FHIR XML or JSON string from your resource object. You can write that string to file.
      Hope this helps! See also the group at https://groups.google.com/forum/#!forum/fhir-dotnet for some more examples and help.

      Reply
      1. DimSouls

        Hello ms Baltus,
        in the FHIR DOTNET google forum you wrote this
        All of the search parameters you mention in your first sentence are standard search parameters for Patient, so that makes it easy. Parameters can be combined into an AND search, by using the syntax described here. This is the RESTful syntax with an HTTP verb.
        If you use the .Net API, you can perform the search by:
        setting up your FhirClient
        creating a SearchParams instance
        adding the search parameters and values to that instance with SearchParams.Add(key, value)
        performing the search with FhirClient.Search(params)
        After you get back the result — if there are any matches — you could use the Patient.id for each result to do a second search. That search will be on the Appointment type, where the search parameter “actor” is equal to the technical id of the patient.
        Alternatively you could do a reverse include of the Appointments. That way you get back only 1 bundle of results, including Patients and their Appointments, but not all servers support the reverse inclusion yet.

        All i want to ask is if you can make an example of that!
        My code is somelithing like this:

        var endpoint = new Uri(FHIRserver_comboBox.Text);
        var client = new FhirClient(endpoint);
        patientName = patientName_txtBox.Text;
        var query = new string[] { “name=” + patientName + “” };
        var bundle = client.Search(“Patient”, query);

        label1.Text = “”;

        foreach (var entry in bundle.Entry)
        {
        Patient p = (Patient)entry.Resource;
        label1.Text = label1.Text + “id: ” + p.Id + ” | ” + “surname: ” + p.Name.First().Family.FirstOrDefault() + ” | ” + “name: ” + p.Name.First().Given.FirstOrDefault() + ” | ” + “birthdate: ” + p.BirthDate + ” | ” + “gender: ” + p.Gender + ” | ” + “careprovider: ” + ???WHAT SHOULD I PUT HERE??? + “” + “\r\n”;
        }

        In careprovider what i write? I found that i can use Practitioner , but how i can do that?

        i was looking at the fhirnetapi pdf and i found this
        var q = new Query()
        .For(“Patient”).Where(“name:exact=ewout”)
        .OrderBy(“birthDate”, SortOrder.Descending)
        .SummaryOnly().Include(“Patient.managingOrganization”)
        .LimitTo(20);

        but the compiler says that Query is obselete….

        Thanks in advance for your help!

      2. Mirjam Baltus

        Yes, Query is obsolete. We use SearchParams to construct a query now, or alternatively you can construct your own string [] with key and value pairs.

        If your server supports the _include parameter, you can search for Patients _plus_ their care providers by using these SearchParams:

        var query = new SearchParams()
        .Where(“name=” + patientName)
        .Include(“Patient:general-practitioner”);

        and then performing the search like this:

        var bundle = client.Search(query);

        The Bundle can then contain multiple resource types, and you will have to look through the Bundle entries to find the Practitioner or Organization that’s referenced in the Patient.generalPractitioner field.

        If the server does not support the _include, you can perform the search like you normally would. Then in your loop where you look at a Bundle entry, you would perform a Read request for the care provider by using the reference in the Patient.generalPractitioner. This of course has the disadvantage that there will be more network traffic, because you call the server for each of the entries.

  9. KB

    Hi,

    How can we going to maintain the security in production domain?
    or
    In live server data would be available for every one?

    Reply
    1. Mirjam Baltus

      The code in this blog is just for demo purposes, to show you you can be up and running with a very basic FHIR app within the hour. There are publically available testservers you can use to test FHIR with, like Vonk (the successor of Spark). But we do not expect all production servers to be open to all. If you want to have a server in a production environment, you will need think about authorization and authentication. The FHIR standard has a page with some security recommendations (http://www.hl7.org/fhir/security.html), but FHIR is not a security standard.

      Reply

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s