Order Catalog Implementation Guide
1.0.0 - STU 1

Order Catalog Implementation Guide, published by HL7 International / Orders and Observations. This guide is not an authorized publication; it is the continuous build for version 1.0.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/fhir-order-catalog/ and changes regularly. See the Directory of published versions

## Spec - Medications

Page standards status: Informative

Detailed specifications for catalogs of medications

### Resources and Profiles

The figure below shows the resources and profiles used to represent catalogs or formularies of medications

When method 1 is chosen by the custodian of the catalog of medications, the catalog references its items: the Composition resource constrained by the Catalog 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 MedicationKnowledge resource constrained by the DrugKnowledge profile and representing an item of the catalog, references the Composition resource constrained by the CatalogHeader profile to represent only the header of the catalog, which holds the general properties of the catalog.

An item of the catalog describes an orderable medication, with its various pharmacological and therapeutic properties, its costs and pricing and packaging, instantiated as a MedicationKnowledge resource linked to a number of supporting resources providing the details of the drug.

### Searching and retrieving drugs from the catalog

#### Searching Approaches

The key searcheable assets in a drug compendium/catalog/formulary are the medications exposed to the consumers of the compendium as instances of MedicationKnowledge.

- Two-step search: A client application browsing the content of the compendium may wish to first get the overview of a collection of drugs at first glance, and then retrieve the full details (such as therapeutic indications, contraindications, warnings, interactions, packaging) associated with the ones of interest. In this case, the first query will perform a simple search on MedicationKnowledge with the desirable criteria listed in the table below ; and then a second narrower search will add the `_include:iterate=*` parameter, to retrieve the selected MedicationKnowledge resource(s) with all their supporting resources (ClinicalUseDefinition, PackagedProductDefinition) in the searchset Bundle.
- One-step search: Conversely a client application may wish to retrieve the full details of a drug (or a set of drugs) at first glance. In this case, it uses the appropriate search criteria for MedicationKnowledge, in combination with the `_include:iterate=*` parameter so as to obtain all the supporting resources of each medication retrieved, in the searchset Bundle.

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

#### Search Parameters for drugs (MedicationKnowledge)

Name | Type | Description | Expression | Role
--- | --- | --- | --- | ---
_lastUpdated | date | Last system point in time of MedicationKnowledge resource |  | can be used with =gt...
classification | token | specific category assigned to the medication | MedicationKnowledge.medicineClassification.classification | For instance WHO-ATC code, or SNOMED CT drug disposition (behavior) code
classification-type | token | Code that identifies this medication | MedicationKnowledge.code |
code | token | specific category assigned to the medication | MedicationKnowledge.medicineClassification.classification | For instance WHO-ATC code, or SNOMED CT drug disposition (behavior) code
catalog | reference | The reference to a Composition resource (profiled by CatalogHeader) owning this item | MedicationKnowledge.extension.where(url='http://hl7.org/fhir/uv/order-catalog/StructureDefinition/CatalogReference').valueReference.reference(Composition) | catalog to search from
doseForm | token | pharmaceutical dose form (e.g.; powder | tablets | capsule ...) | MedicationKnowledge.definitional.doseForm |
ingredient-code | token | A code representing a substance in the medication | MedicationKnowledge.definitional.ingredient.item.concept |
ingredient | token | Reference to a resource representing a substance in the medication | MedicationKnowledge.definitional.ingredient.item.reference |
name | string | The drug name | MedicationKnowledge.name |
packaging-cost | quantity | The cost in money of the packaged medication | MedicationKnowledge.packaging.cost.costMoney |
product-type | token | e.g. branded product, therapeutic moiety, generic product, innovator product | MedicationKnowledge.productType |
status | token | active | inactive | entered-in-error | MedicationKnowledge.status | narrow to active or retired medications

#### Examples of searching and retrieving medications from catalogs

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.

One particular drug compendium, is assumed to have 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 all drug catalogs

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

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

##### Retrieve all details for a medication

    GET [base]/MedicationKnowledge?code=783043004&_include:iterate=*

Obtains the full content of instances of MedicationKnowledge with SNOMED CT code 783043004 |Product containing precisely afatinib (as afatinib dimaleate) 20 milligram/1 each conventional release oral tablet (clinical drug)|, accompanied by their supporting resources referenced by this MedicationKnowledge: {Composition, ClinicalUseDefinition, PackagedProductDefinition, ...}. The anwser Bundle contains the full details for each drug retrieved: An entry for each matching MedicationKnowledge and, below it, as many entries as resources referenced by this one (recursively).