# Spec - Medications - Order Catalog Implementation Guide v1.0.0

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

## Spec - Medications

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

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](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 MedicationKnowledge resource constrained by the [ DrugKnowledge](StructureDefinition-DrugKnowledge.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 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](http://hl7.org/fhir/medicationknowledge.html) 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](http://hl7.org/fhir/medicationknowledge.html). 

* **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)

| | | | | |
| :--- | :--- | :--- | :--- | :--- |
| _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). 

