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