Use case 1: Retrieve lab results by care provider

Introduction

In some country, there is a need to expose laboratory results through a FHIR interface. This service has to be read only and allow the receiver to view information about the laboratory result, patient, and performer they need.

A care provider wants to be able to retrieve lab results of a certain patient over a specific period of time. Including Patient information, information of the lab that performed the patient and of course all relevant reference ranges for the outcome of the result.

Through a workshop with consumers from different regions, we have established the following user stories.

  1. Find Lab Results by patient identifier
  2. Find Lab Results by time period
  3. Find Lab Results by type of lab observation
  4. Find Lab Results by method qualifier

We need to be able to extend the functionality of the interface, as new stories and needs are uncovered.

Example UML flow

UML-sequence-diagram-featured-image

Actors

Transaction group Transaction Actor Role
Retrieve Laboratory Results(PULL) Retrieve laboratory results request Laboratory Results Consumer Request laboratory results from the XIS
Retrieve laboratory results response Laboratory Results Responder Serves laboratory results to the PHR

Request - Laboratory Results Consumer

Trigger Events

When the Laboratory Results Consumer wants to obtain laboratory results, it issues a retrieve laboratory results request message.

Message Semantics

The Laboratory Results Consumer executes an HTTP GET conform to the FHIR [http://hl7.org/fhir/http.html RESTfull] and [http://hl7.org/fhir/search.html search] specification against the XIS's Observation endpoint. This search query URL is configurable by the Laboratory Results Consumer and has the following format.

GET [base]/Observation?[parameters]{&_format=[mime-type]}

Search Parameters

The Laboratory Results Consumer may supply, and the Laboratory Results Responder shall be capable of processing, all query parameters listed below. These search parameters are a selection of the defined search parameters by the HL7 FHIR specification search parameters of [http://hl7.org/fhir/STU3/observation.html#search Observation].

Name Type Description
patient reference The subject that the observation is about (if patient)
date date Obtained date/time. If the obtained element is a period, a date that falls in the period.
code token The code of the observation type
method-qualifier token To filter on Observation.method qualifier

Including other resources in search results

The Laboratory Results Consumer may request that the Laboratory Results Responder return resources related to the search results, in order to reduce the overall network delay of repeated retrievals of related resources. This is useful when the Laboratory Results Consumer is searching on a clinical resource, but for every such resource returned, the client will also need for example the subject (Patient resource) or performer (Organization / Practitioner resource) or Specimen resource that the clinical resource refers to. The client can use the _include parameter to indicate that the subject resources be included in the results. An example is shown below.

Example search URLs

GET [base]/Observation

Retrieves all Observation resources.

GET [base]/Observation?patient=1123123&code=http://loinc.org|718-7

Retrieves all '' Hemoglobin [Mass/volume] in Blood'' Observation resources of Patient with ID 1123123

GET [base]/Observation?code=http://loinc.org|718-7&date=ge2010-01-01

Retrieves all '' Hemoglobin [Mass/volume] in Blood'' Observation resources that have an effective date greater than 01-01-2010.

GET [base]Observation?code=http://loinc.org|718-7&_include=Observation:performerdate=ge2010-01-01&date=le2011-12-31

Retrieves all '' Hemoglobin [Mass/volume] in Blood'' Observation resources that have an effective date within a 2 year period and includes the perfomer information in the search results.

GET [base]/Observation?code=http://loinc.org|718-7&method-qualifier=http://example-Tx.org|QualifierCode01

Retrieves all '' Hemoglobin [Mass/volume] in Blood'' Observation resources that have a method-qualifier code 'QualifierCode01'.

Expected Actions

The Laboratory Results Responder shall process the query to discover Observation resources that match the search parameters given.

Response - Resonder

To demonstrate the IG editor's syntax highlighting of code, below an example of C# code in creating a SearchSet Bundle with containing a Patient.

        static void CreateBundle()
        {
            // Construct a Patient resource conforming to the LabPatient profile
            var pat = new Patient();

            pat.Id = "id12312312";

            pat.Meta = new Meta();
            pat.Meta.ProfileElement.Add(new FhirUri("http://devdays-example-ig.com/fhir/StructureDefinition/DevDaysIGtutorial-Patient"));

            var bsn = new Identifier()
            {
                Use = Identifier.IdentifierUse.Official,
                System = " http://fhir.nl/fhir/NamingSystem/bsn",
                Value = "8741987136"
            };

            pat.Identifier.Add(bsn);

            var name = new HumanName().WithGiven("Mickey").WithGiven("M.X.").AndFamily("de Muis-van het Huis");
            name.FamilyElement.AddExtension("http://hl7.org/fhir/StructureDefinition/humanname-partner-prefix", new FhirString("de"));
            name.FamilyElement.AddExtension("http://hl7.org/fhir/StructureDefinition/humanname-partner-name", new FhirString("Muis"));
            name.FamilyElement.AddExtension("http://hl7.org/fhir/StructureDefinition/humanname-own-prefix", new FhirString("van het"));
            name.FamilyElement.AddExtension("http://hl7.org/fhir/StructureDefinition/humanname-own-name", new FhirString("Huis"));

            name.AddExtension("http://hl7.org/fhir/StructureDefinition/humanname-assembly-order", new Code("NL3"));

            pat.Name.Add(name);

            pat.Gender = AdministrativeGender.Male;

            // Create the searchset bundle

            var b = new Bundle();
            b.Type = Bundle.BundleType.Searchset;
            b.Id = "MirjamsTechnischeBundleId1";

            b.Total = 1;

            var e = new Bundle.EntryComponent();
            e.FullUrl = "http://example.org" + pat.ResourceType.ToString() + pat.Id;
            e.Resource = pat;

            b.Entry.Add(e);

            Console.WriteLine(FhirSerializer.SerializeResourceToJson(b));
        }