# Spec - Laboratory services - Order Catalog Implementation Guide v1.0.0

* [**Table Content**](toc.md)
* **Spec - Laboratory services**

## Spec - Laboratory services

| |
| :--- |
| *Page standards status:*[Informative](http://hl7.org/fhir/R5/versions.html#std-process) |

This page provides the detailed specifications for catalogs of laboratory diagnostic services.

### Resources and Profiles

 The figure below shows the resources and profiles used to represent catalogs of laboratory diagnostic services 

When method 1 is chosen by the custodian for the catalog of laboratory services, the catalog references its items: the [Composition](http://hl7.org/fhir/composition.html) resource constrained by the [ Catalog](StructureDefinition-Catalog.md) profile to represent the whole catalog, references the items of this catalog from its Composition.section.entry elements.

When method 2 is chosen instead, the catalog is referenced by its items: Each PlanDefinition resource constrained by the [ LabServiceDefinition](StructureDefinition-LabServiceDefinition.md) profile, and representing an item of the catalog, references the [Composition](http://hl7.org/fhir/composition.html) resource constrained by the [ CatalogHeader](StructureDefinition-CatalogHeader.md) profile to represent the catalog header. This catalog header holds only the general properties of the catalog.

An item of the catalog is a laboratory service instantiated as a [PlanDefinition](http://hl7.org/fhir/plandefinition.html), which represents either a test (type=test) or a panel (type=panel). A panel is a set of tests and/or panels. 

At order entry time the computerized physician order entry applies the PlanDefinition to the current patient context, producing one or more [ServiceRequest](http://hl7.org/fhir/servicerequest.html) resources to convey the order for the laboratory service in case FHIR is used for placing orders, or feeding a v2 laboratory order message (OML) in case HL7 v2 is used for the same purpose. 

The PlanDefinition conveys the general properties of the item: identification, names and codings, orderability, applicability, jurisdictions, billing, status, possible replacement by another item, gender or species restrictions, goals, bibliographic references and justifications, expected input documents (such as patient consent for genetic testing).

If present, PlanDefinition.action.definitionCanonical references the instance of ActivityDefinition representing the main operational procedure performed to carry this laboratory service. PlanDefinition.action.definitionCanonical may be not present, in which case, the top-level action has sub-actions referencing multiple instances of ActivityDefinition. This is illustrated by action[.action[.action]].definitionCanonical in the diagram, which potentially represents more than one action. 

PlanDefinition.action:SpecimenRequested (0..*) conveys the requirements for biological specimens needed as input by the laboratory service.

PlanDefinition.action.definitionCanonical references one instance of [ActivityDefinition](http://hl7.org/fhir/activitydefinition.html) representing the main operational procedure performed to carry this laboratory service. ActivityDefiniton is constrained by the [LabProcedureDefinition profile ](StructureDefinition-LabProcedureDefinition.md). It references the observations expected by the laboratory as input alongside the order, and the observations that will be produced as output of the procedure. 

In most cases the PlanDefinition.action has no sub-action, and therefore PlanDefinition references a single ActivityDefinition. 

In some cases the laboratory service (panel or super-panel) embeds other services (panels and/or tests), which are already described in the catalog as standalone services (orderable or not). These nested services have, each, their own instance of PlanDefinition referenced from PlanDefinition.relatedArtifact (type = composed-of) of the embedding service. And in addition, each of the embedded tests or panels is described as a sub-action (PlanDefinition.action.action), which references an ActivityDefinition representing the nested laboratory procedure with its own observations, which will be added to those of the embedding service.

When a PlanDefinition of a laboratory service has multiple sub-actions, these sub-actions are assembled in a logical group (groupingBehavior = logical-group), with a selection behavior specified by the selectionBehavior element. Each of these sub-actions either references an ActivityDefinition or is redefined as a nested logical group introducing sub-sub-actions referencing ActivityDefinition instances. 

Some of the sub-actions may also correspond to reflex procedures, triggered by a particular event or result in the parent procedure.

The sub-actions (and possibly sub-sub-actions) are assembled in logical groups, with a selection-behavior expressing which logic applies:

* **all:** all sub-actions of the group are taken
* **exactly-one:** one and only one sub-action of the group is taken (choice)
* **any:** any number of reflex sub-actions of the group is taken, depending on which trigger associated with each comes true.

 This nesting of actions allows to build trees of laboratory services, reflecting the reality of some complex diagnostic panels. (e.g. [ LOINC's HIV susceptibility panel by Genotype method](https://loinc.org/49660-4/ LOINC 49660-4) nesting 3 levels of panels and tests)

Input and output observations of the service are defined as instances of [ObservationDefinition](http://hl7.org/fhir/observationdefinition.html) (constrained by the [InputObservationDefinition profile](StructureDefinition-InputObservationDefinition.md) for observations expected from the ordering clinician, or by the [ LabObservationDefinition profile](StructureDefinition-LabObservationDefinition.md) for observations produced by the lab service and reported back to the clinician), with their quantitative (units, decimal precision, conversion factor, normal and therapeutic ranges) and/or qualitative (authorized values, normal values, critical values, preferred report name) characteristics.

Specimens required by the service are defined as instances of [SpecimenDefinition](http://hl7.org/fhir/specimendefinition.html) conformant to the [LabSpecimenDefinition profile](StructureDefinition-LabSpecimenDefinition.md), which enables to describe patient preparation requirements, collection procedures, types of containers to be used, minimum volume needed, rejection criteria, retention time, handling requirements before testing. An instance of SpecimenDefinition may specify one preferred testable specimen and multiple alternates, each with its proper physical characteristics, handlings, requirements and rejection criteria. 

A laboratory service may provide more or less details about its billing. It may provide a textual billing summary as part of the PlanDefinition instance. It may also list the billing codes of a billing nomenclature, attached to it, still within the PlanDefinition instance. In addition, the service may specify for each billing code attached to it, what are the specific clinical focus that apply to this code, and what are its price components. These details are conveyed by a [ChargeItemDefinition](http://hl7.org/fhir/chargeitemdefinition.html) resource constrained by the [LabChargeItemDefinition profile](StructureDefinition-LabChargeItemDefinition.md)

### Searching and retrieving Laboratory Services

#### Searching Approaches

 The key searcheable assets in a laboratory compendium are the laboratory services exposed to the consumers of the compendium. Each laboratory service is represented by an instance of the [PlanDefinition](http://hl7.org/fhir/plandefinition.html) resource, constrained by the [LabServiceDefinition](StructureDefinition-LabServiceDefinition.md) profile. 

* **Two-step search**: A client application browsing the content of the compendium may wish to first get the overview of a collection of services at first glance, and then retrieve the full details associated with the services it is interested in (including specimens, input observations, lab results). In this case, the first query will perform a simple search on *PlanDefinition* with the desirable criteria listed in the table below ; and then the second search will add the **`_include:iterate=*`** parameter, to retrieve the PlanDefiniton resource(s) associated with all supporting resources (ActivityDefinition, ChargeItemDefinition, Composition, SpecimenDefinition, ObservationDefinition ...) in the *searchset Bundle*.
* **One-step search**: Conversely a client application may wish to retrieve the full details of a service (or a set of services) at first glance. In this case, it uses the appropriate search criteria for PlanDefinition, in combination with the **`_include:iterate=*`** parameter, so as to obtain all the resources supporting each laboratory service which satisfies the criteria, assembled in the *searchset Bundle*.

Catalog servers may limit the iteration depth to an appropriate level for performance sake.

#### Search Parameters for Laboratory Services (PlanDefinition)

| | | | | |
| :--- | :--- | :--- | :--- | :--- |
| _lastUpdated | date | Last system point in time of PlanDefinition resource |  | can be used with =gt... |
| action-code | token | service code | PlanDefinition.action.code | LOINC code or local code of the service |
| billing-code | token | A billing code associated with the service | PlanDefinition.extension.where(url='http://hl7.org/fhir/uv/order-catalog/StructureDefinition/ServiceBillingCode').(value as Reference).reference(ChargeItemDefinition).resolve().code or PlanDefinition.extension.where(url='http://hl7.org/fhir/uv/order-catalog/StructureDefinition/ServiceBillingCode').(value as CodeableConcept) | The FHIRPath expression to be checked |
| catalog | reference | The reference to a Composition resource (profiled by CatalogHeader) owning this item | PlanDefinition.extension.where(url='http://hl7.org/fhir/uv/order-catalog/StructureDefinition/CatalogReference').valueReference.reference(Composition) | services of one catalog |
| composed-of | reference | lab service containing another lab service | PlanDefinition.relatedArtifact.where(type='composed-of').resource(PlanDefinition) | super-panels encompassing this test or panel |
| context | reference | use context assigned to the laboratory service | (PlanDefinition.useContext.value as CodeableConcept) |  |
| date | date | Publication date of service's business version | PlanDefinition.date | can be used with =gt... |
| description | string | The description of the laboratory service | PlanDefinition.description |  |
| gender | token | Services with a useContext representing a particular gender | (PlanDefinition.useContext.where(code='gender').value as CodeableConcept) | services restricted to a particular gender |
| jurisdiction | string | lab service jurisdiction | PlanDefinition.jurisdiction | e.g. country where service is usable |
| last-review-date | date | Last review date of the service | PlanDefinition.lastReviewDate | can be used with =gt... |
| name | string | The service computational name | PlanDefinition.name |  |
| orderable | token | (true: service with a useContext belonging to slice Orderable of LabServiceDefinition profile ; false: the opposite | PlanDefinition.useContext.slice(http://hl7.org/fhir/uv/order-catalog/StructureDefinition/LabServiceDefinition, Orderable).exists() | FHIRPath expression to be checked |
| publisher | string | lab service publisher | PlanDefinition.publisher |  |
| status | token | lab service status | PlanDefinition.status | narrow to active or retired services |
| task | token | Service with a useContext representing a particular task (e.g. LABOE for orderable service, LABRREV for service that can be added by the pathologist) | (PlanDefinition.useContext.where(code='task').value as CodeableConcept) | services associated with the particular task |
| title | string | The service title | PlanDefinition.title |  |
| topic | token | topic associated with the service | PlanDefinition.topic | various categorizations of the service |
| type | token | lab service type | PlanDefinition.type | narrow to type panel or type test |
| url | uri | The uri that identifies the laboratory service | PlanDefinition.url |  |

#### Examples of searching and retrieving laboratory services

In all examples below, [base] represents the endpoint of the catalog server. 

The answer of the server comes as a Bundle of type 'searchset' encapsulating the resources selected by the search.

There is one particular laboratory service catalog, which has Composition.id "a1" on the server.

##### List all catalogs of the server

```
GET [base]/Composition?type:text=Catalog&_summary=true
```

 Obtains the summary of every catalog available on the server.The anwser Bundle contains one entry with a Composition resource for each catalog found.

##### List available laboratory service catalogs

```
GET [base]/Composition?type:text=Catalog&category=laboratory&_summary=true
```

 Obtains the summary of every laboratory service catalog available on the server. The anwser Bundle contains one entry with a Composition resource for each catalog found.

##### List recently updated blood chemistry tests and panels of one catalog

```
GET [base]/PlanDefinition?catalog=Composition/a1&topic=http://snomed.info/sct|166312007&date=gt20200323T10:00:00Z+0100&_summary=true
```

 Obtains the summary of the laboratory services from catalog of id a1, which are indexed by blood chemistry topic (coded in this example with SNOMED CT 166312007 |Blood chemistry| concept). The anwser Bundle contains one entry with a PlanDefinition resource for each laboratory service of catalog a1 associated with blood chemistry topic, and created or updated since March 23rd 10am.

##### Services of a catalog embedding a test or panel

```
GET [base]/PlanDefinition?catalog=Composition/a1&composed-of=PlanDefinition/s123&_summary=true
```

 Lists the laboratory services from catalog of id a1, which embed laboratory service of id s123. The anwser Bundle contains one entry with a PlanDefinition resource for each service found with a relatedArtifact.where(type='composed-of').PlanDefinition/s123.

##### Retrieve all details for a laboratory service

```
GET [base]/PlanDefinition?_id=s123&_include:iterate=*
```

 Obtains the full content of PlanDefinition of id s123, accompanied with all resources referenced by this PlanDefinition: {Composition, ActivityDefinition, ObservationDefinition, SpecimenDefinition, PlanDefinition (as related artifacts in case this service embeds other panels or tests)}. The anwser Bundle contains one entry with PlanDefinition resource s123, and below it, as many entries as resources referenced by this one (recursively). Thus the Bundle provides the fullly detailed description of this laboratory service. 

### Administering laboratory services

When the roles **catalog owner** and **catalog custodian** are played by two different systems the former is a FHIR client of the latter, granted with administration permissions (create, update, delete, patch) on the catalog content. The interactions between the two systems follow the transversal technical specifications exposed in section [ *Administer a catalog through the FHIR API* of the Interactions page of this guide](interactions.md#AdminCatalog).

 The **catalog owner** updates the content of the catalog on the **catalog custodian** in a transactional manner, by posting a `transaction Bundle` containing all the updates to be performed synchronously: 

```
POST [base]
```

with the `transaction Bundle` in the body of the request, as shown in [ example-lab-test-creation-transaction-request](Bundle-example-lab-test-creation-transaction-request.md). 

The **catalog custodian** performs the requested transaction and returns back a `transaction-response Bundle`, as shown in [ example-lab-test-creation-transaction-response](Bundle-example-lab-test-creation-transaction-response.md). 

