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.
- Find Lab Results by patient identifier
- Find Lab Results by time period
- Find Lab Results by type of lab observation
- 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
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("https://fake-acme.org/fhir/StructureDefinition/ACME-base-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));
}