Providing information about the customer interface requirements for FHIR resources which represent medication data pertaining to a Patient, namely:

• MedicationDispense

• MedicaionRequest

• MedicationStatement

All dosages must conform to the following requirements. If any of the below requirements do not satisfy your use case, please inform PKB and we can discuss expanding the capabilities to suit your needs.

• Only the first iteration of the dosage array is observed, all subsequent elements within the dosage array on all resource types will be ignored. “First iteration” in all instances is defined as the dosage element with a sequence equal to 1 or the first in the array if this is not present. Similarly, most subsequent information is derived from the first iteration of the doseAndRate array, with all subsequent elements within this array being ignored.

  • Multiple dosages with a sequence value of 1 is an error case.

  • Multiple doseAndRate elements within a single dosage is an error case.

  • If no dosage has a sequence value of 1, the first instance in the array is taken regardless of other sequence values. This means a dosage with a higher sequence value than those lower down in the array could be selected, depending on the data order.

  • When sending multiple dosage sequences in a MedicationStatement, use the dosage.text field to provide a single summary that describes all sequences. This text will be displayed in the PKB UI and should reflect the overall dosing instructions.

• The dose value is derived from the doseAndRate, specifically the doseQuantity value element. doseRange is not currently supported.

• The dose unit is derived from the doseAndRate, specifically the doseQuantity system, code and unit elements.

  • If providing a code and system, you must provide a dose unit which is either UCUM or SNOMED CT, which means setting doseQuantity#system to either http://unitsofmeasure.org or http://snomed.info/sct respectively. UCUM is the standard preferred by the FHIR specification but there is a general acceptance within health interoperability that SNOMED is required to fulfil those units which represent non-UCUM values.

  • A data absent reason is permissible for the doseQuantity system in order to satisfy FHIR schema requirements, but note that this is strongly advised against as it renders the interpretation of the dosage unit vague and therefore liable to misinterpretation and clinical risk by the end user. See example below

  • This dose code must be from the below supported list. If you wish to send in a dose code for a unit which are not currently supported, please inform PKB and we can discuss expanding these capabilities to suit your needs.

  • UCUM dose units, as per specification requirements, are case sensitive. For millilitres, for example, mL is valid, ml is not.

  • An alternative approach is to provide the dose unit textually through the doseQuantity#unit element. It is preferred to provide a coded unit representation using the above requirements, as this allows for structured mapping to internal PKB medication units. Note that if both a code+system and unit are provided, preference is given to a valid code+system over the unit.

• The dose frequency is derived from the first dosage iteration and can be drawn from several elements on this complex subtype.

  • “As needed” is derived from dosage#asNeeded and set to true if asNeededBoolean is set to true. If the asNeeded element is a codeableConcept, as needed is always set to true. The contents of the codeableConcept are not displayed in the PKB UI.

    • For example, where a medication is prescribed “as needed for pain” and “Pain” is sent using asNeededCodeableConcept, PKB will render this in the UI simply as “as needed”. The underlying coded reason is retained in the resource but is not displayed.

  • “As directed” is derived from dosage#timing#code and is set to true if this element is populated: as per the valueSet definition for this element, these are all a permutation of instruction to the patient. The specifics of the timing are not observed.

    • If dosage.timing.code is populated (with any value from the permitted value set), PKB will derive and display “as directed” in the UI. The specific coded instruction provided in timing.code is not displayed.

  • Specific frequencies (i.e. take this medication every 1 day) are derived from dosage#timing#repeat, specifically:

    • The frequency with which the medication is taken is derived from the period

    • The frequency unit is derived from the period unit

  • Other elements on the dosage#timing are currently not observed, such as dayOfWeek or timeOfDay