Entity: Medication web specification

Overview

This page provides more detail on how the web interface displays medication information, which it fetches from the Aggregated FHIR API. Note:

Whilst this page explains which elements are inspected, the web interface does not provide any feedback about which/whether other FHIR elements are present in the database that are not being displayed.
Some information is displayed that is not fetched from the Aggregated FHIR API, such as attachments.

The Manual provides more information on the functionality; this page is aimed at a technical audience who need to understand the relationship between the FHIR resources and the web interface.

FHIR® Resources

The web interface populates Medicines from the following FHIR resources:

Summary

The web interface shows a list of medications. These are separated into “Current medicines” and “Past medicines”. A medication is considered to be current unless either of the following are true:

The medication has an End Timestamp which is in the past
The medication Status is UNKNOWN or not ACTIVE

The current medications are ordered by start timestamp descending, then end timestamp descending, and then alphabetically.

Past medications will be visually grouped together when they match on the following criteria:

medicationCodeableConcept
Source Organization
Access route

Mappings

Component	MedicationRequest	MedicationStatement

Component

MedicationRequest

MedicationStatement

Status

This is not shown explicitly, but is included in the logic which determines if the medication is current or past.

status

status code mappings (FHIR → PKB):

active → ACTIVE
unknown → ACTIVE
entered-in-error → INACTIVE
completed → INACTIVE
stopped → INACTIVE
on-hold → INACTIVE
cancelled → INACTIVE
draft → INACTIVE

status

status code mappings (FHIR → PKB):

active → ACTIVE
unknown → ACTIVE
entered-in-error → INACTIVE
completed → INACTIVE
stopped → INACTIVE
on-hold → INACTIVE
intended → INACTIVE
not-taken → INACTIVE

Substance

The medication substance is shown in 2 places:

A primary display string. This is a simple display string shown in the unexpanded row view.
Additional details. Information about the medication code and system values are shown in the expanded row view.

<conditional>

If medicationReference is populated:

(Note: Medication is a merged resource type; the merge logic affects the content of the resource.)

Primary display string

If code.text is populated: the same text
else: the last populated code.coding[x].display
else: the empty string

Additional details

The code and system of all code.coding Codings are shown. Other elements of the Coding are not shown.

Note: the system will be replaced with user-friendly name when known to PKB.

Else:

Primary display string

If medicationCodeableConcept.text is populated: the same text
else: if a Coding is present and contains the http://fhir.patientsknowbest.com/structuredefinition/primary-coding extension: the display of the same Coding
else: the first populated medicationCodeableConcept.coding[x].display
else: the empty string

Additional details

As per the logic above for primary display string.

Start Timestamp

If this extension is present: http://nictiz.nl/fhir/StructureDefinition/zib-Medication-PeriodOfUse

extension[x]: valuePeriod.start

Else:

authoredOn

effectivePeriod.start

End Timestamp

If this extension is present: http://nictiz.nl/fhir/StructureDefinition/zib-Medication-PeriodOfUse

extension[x]: valuePeriod.end

Else:

No value.

effectivePeriod.end

For the dosage and frequency-related information, except where noted PKB will use the Primary Dosage, which is the Dosage determined as follows:

Determine which Dosage list to inspect
- If the resource is a MedicationRequest: then use dosageInstruction
- Else if the resource is a MedicationStatement: then use dosage
The select 1 Dosage from the list as follows:
- If there is exactly one Dosage where sequence is 1, then use the same
- Else: use the first in the list

“Structured Frequency”

(Frequency Priority / Frequency Value / Frequency Units)

If asNeededCodeableConcept is present, or asNeededBoolean is set to true:

“Take as needed” will be shown; i18n is applied.

Else if Timing.code is populated with any value:

“Take as directed” will be shown; i18n is applied.

Else if Timing.repeat has frequency set to 1, periodUnit has a value of either “d” or “h”, and period is a known integer for the corresponding periodUnit:

A corresponding textual description; i18n is applied.

Example: “Every four hours”

Else:

No value.

Frequency Text

This is shown underneath the main line for the medication.

<conditional>

If text is populated: the same text

Else if there was no Structured Frequency found, and Timing.repeat is populated with both period and periodUnit:

If frequency element is also populated:

“<frequency> time(s) every <period> <periodUnit>(s)” will be generated and shown; i18n is not applied.

Else:

“Every <period> <periodUnit>(s)” will be generated and shown; i18n is not applied.

Else:

No value.

Dose Value

doseAndRep[0].doseQuantity.value

Dose Units / Medication Unit

The dose unit is shown in 2 places:

A primary display string. This is a simple display string shown in the unexpanded row view.
- Note: this is only displayed if Dose Value is populated.
Additional details. Information about the dose unit code and system values are shown in the expanded row view.

<conditional>

If doseAndRep[0].doseQuantity has a code, no unit and no system:

The code is assumed to be one of the supported unit values as per [[Medication Unit]].

Primary display string

The primary display string will be an appropriate display name with i18n applied.

Additional details

There is no additional code information to display.

Else:

We inspect the first Dosage (which might differ from the previously determined Primary Dosage) and inspect doseAndRep[0].doseQuantity for the http://fhir.patientsknowbest.com/structuredefinition/dose-units extension.

Primary display string

If text is populated: the same text
else: if a Coding is present and contains the http://patientsknowbest.com/structuredefinition/primary-coding extension: the display of the same Coding
else: the first populated coding[x].display
else: the empty string

Additional details

The code and system of all Codings are shown. Other elements of the Coding are not shown.

Note: the system will be replaced with user-friendly name when known to PKB.

Instructions

The instructions displayed will be the concatenation of all of the following information, in this order:

Dosage.patientInstruction
Each Dosage.additionalInstruction[x].text value