Order Catalog Implementation Guide
current - CI Build International flag

Order Catalog Implementation Guide, published by HL7 International - Orders and Observations Work Group. This is not an authorized publication; it is the continuous build for version current). 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

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

Resources used by a catalog or formulary 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).