Drug Orders: Order Templates modelling

@burke thanks for the detailed proposed design. We have created an epic, would be awesome if you had a look and possibly curate the underlying tickets

@burke what happens if a particular drug has no order template defined? Should it be orderable? I’m asking because the current implementation ensures that you can only order for a drug that has a defined template (currently defined within common-medication.json, and this). Do we want to keep this kind of behaviour?

That being said, I would wish to know whether we have agreed on a final schema of the Order template? Here is the current schema: openmrs-esm-patient-chart/common-medication.ts at master · openmrs/openmrs-esm-patient-chart · GitHub.

export interface CommonMedication {
  name: string;
  uuid: string;
  strength: string;
  dosageUnits: Array<CommonMedicationDosageUnit>;
  route: Array<CommonMedicationRoute>;
  commonFrequencies: Array<CommonMedicationFrequency>;
  commonDosages: Array<CommonMedicationDosage>;

cc: @eudson, @mseaton, @jdick

1 Like

In my view, we want order templates to help pre-select common values, not to determine what is orderable or not. Otherwise, we’ll wind-up with a system that encourages people to write orders on paper and then why would they use the EMR for ordering?

1 Like

I agree with @ibacher. Templates can facilitate ordering by providing pre-filled orders or helping direct providers to preferred/common values for fields within the ordering form. The absence of a template means the system cannot assist the provider with the orderable, but should not prevent ordering. Most sites will focus efforts on making template for common orderables and may not have templates prepared for uncommon or new orderables (which should still be orderable).

We need an approach to handle multiple order template types. While your work is initially focusing on drug orders, we need to leave space to accommodate templates for other types of orders (tests, referrals, etc.). And we need to anticipate versioning, since our schemas will likely evolve over time (possibly not always in backwards-compatible ways).

We can either follow the pattern of the yet-to-be-used order_set_member table by always storing template & type alongside each other (assuming template type is a URN that can include version) OR we require all order temple JSON to include a type property to be valid… something like:

  "type": "https://schema.openmrs.org/order/template/drug/simple/v1",

In the case of drug orders, the schema needs to recognize that the dosing instructions type (e.g., simple vs. free text for now and eventually could be taper, combination, etc.), since each dosing instruction type uses a different set of fields within the order form.

Note that templates do not provide common answers for order fields (as your “CommonMedication…” names suggest; rather, they provide pre-defined default ± choices for a specific way to order something. At the moment, we are talking about the default templates for drug orders, but there are other ways we will likely be using templates in the future – e.g., within order sets (defining how a drug is typically ordered when admitting a patient for gall bladder surgery) or linked to diagnoses (defining how a drug is ordered when treating malaria).

So, in approaching a template, we need to consider:

  • Templates are not just for drug orders
  • An order template provides default values and/or choices for one way of ordering something (whether general use or context-specific)
  • Part of a drug order form is dose instruction type (see drug_order) which, in turn, defines the schema for dosing fields. Simple dosing has dose + units + route + frequency + asNeeded + asNeededCondtion + dosing instructions; whereas, free text dosing just has dosing instructions.

Issues with your current CommonMedication interface:

  • Doesn’t accommodate dosing type (currently simple vs free text; others will come later)
  • Doesn’t allow for default ± choices for each field
  • Strength is determined by drug (via drug_id), so not needed
  • For simple dosing type, missing some fields (e.g., as needed, as needed condition, additional instructions)

I would expect our schema to include pointer to a concept ± drug along with a JSON-based order template that looks something like my examples above. But we need a pattern for field values that can communication one or more choices and optionally indicate which is the default value (e.g., an array of values with one optionally having default=true).

  "type": "https://schema.openmrs.org/order/template/drug/simple/v1",
  "dosing_type": "org.openmrs.SimpleDosingInstructions",
  "dosing_instructions": {
    "dose": [ { "value": number, "default": true } ]
    "units": [ { "value":"<Concept>", "default":true } ],
    "route": [ { "value":"<Concept>", "default":true } ],
    "frequency": [ { "value":"<Frequency>", "default":true } ],
    "asNeeded": true,
    "asNeededCondtion": [ { "value": "string", "default":true } ],
    "instructions": [ { "value""string", "default":true } ]

It’s a lot to cover and I’m sure I’ve left gaps. Let me know where you have questions.

@burke Any chance you can draft and share some examples of fully fledged templates? Two examples would work like a charm. One classified as "org.openmrs.SimpleDosingInstructions" and the other as free text.

What is the technical use or meaning of attributes: asNeeded & asNeededCondtion?

@burke I also think the dosingInstructions.units, route and maybe frequency could have a name or display property for better performance experience.

I think we could also add numberOfPills to dosingInstructions.dose:

"dose": {
     "value": "81 mg",
     "numberOfPills": 1

Sure. I doubt I can get every detail covered or without mistakes, but I can give it a try. :slight_smile: In fact, while writing these out, I realized (as with FHIR’s doseQuantity), the dose and its units should be paired rather than treated as independent choices within the simple dosing order template.

Here, I’ve taken a stab at writing out details for two order template entries, one for a drug with simple dosing and another with a drug with free text dosing:

Simple Dosing example

Attribute Value
order_template_id 1
name “abacavir 300 mg daily”
description “Standard dosing of abacavir”
concept_id <FK to local concept for abacavir>
drug_id <FK to drug entry for abacavir 300 mg tablet>
template see below
date_created 2022-08-01 00:01:02:03
created_by <FK to author’s user account>
date_changed null (or when entry was changed)
changed_by null (or FK to user who changed entry)
Click for template...
  type: "https://schema.openmrs.org/order/template/drug/simple/v1",
  dosingType: "org.openmrs.SimpleDosingInstructions",
  dosingInstructions: {
    dose: [ {
        value: 300,
        unit: "mg",
        default: true
    } ],
    route: [{
      value: "oral",
    } ],
    frequency: [{
      value: "twice daily",
    asNeeded: false,
    instructions: "with or without food"

Free Text example

Attribute Value
order_template_id 2
name “Levonorgestrel standard dosing”
description “Standard dosing of levonorgestrel to avoid unwanted pregnancy”
concept_id <FK to local concept for levonorgestrel>
drug_id <FK to drug entry for levonorgestrel 1.5 mg tablet>
template see below ††
date_created 2022-08-01 00:01:02:03
created_by <FK to author’s user account>
date_changed null (or when entry was changed)
changed_by null (or FK to user who changed entry)
†† Click for template...
  type: "https://schema.openmrs.org/order/template/drug/simple/v1",
  dosingType: "org.openmrs.FreeTextDosingInstructions",
  dosingInstructions: "One tablet by mouth as soon as possible within 72 hours of unprotected sexual intercourse or suspected contraceptive failure"

asNeeded is a boolean that’s true for simple dosing where the drug is administered conditionally (commonly referred to as “PRN”, which stands for pro re nata). When asNeeded is true, then asNeededCondition is required and should contain the condition(s) when a dose should be given. For example:

Prescription asNeeded asNeededCondition
paracetamol 500 mg by mouth every 6 hours false null (ignored)
paracetamol 500 mg by mouth every 6 hours as needed for pain true “pain”

Sure. An optional “name” property that can be filled with the name of the corresponding concept/frequency for performance might be okay (where name is assumed to be an exact match of the concept or frequency.concept name and the name of the concept or frequency.concept is always considered “truth” if there’s a discrepancy). But which name would be used in a system that supports more than one language?

Some reasons I’m not sure about hardcoding number of pills into the schema:

  • Not all drugs are pills. Tablets and capsules could be treated as “pills” for calculations, but some drugs are dosed in milliliters or as topical applications, where number of pills wouldn’t make sense.
  • A dose could be “1 pill”, in which case number of pills is redundant.
  • I don’t see number of pills in FHIR’s dosage structure
  • When units match, “number of pills” could be inferred from dose ÷ strength
1 Like

Just to add another reason: the number of pills (at least in general) relates to how medication is dispensed not how it is ordered. Quick example: if the script is for 500 mg of paracetamol but the pharmacy only has 250 mg pills on hand, the number of pills dispensed will be doubled, even though the script is identical. Where the number of pills is the relevant dosing factor, I’d expect you’d have something like:

dose: [{
    value: 20,
    unit: "tablet"

I agree @ibacher . Just a little addition, highlighting from @burke’s pseudo template:

dose: [ {
        value: 300,
        unit: "mg",
        default: true
    } ]

I think it should be something like:

dose: [ {
        value: "300mg",
        unit: "tablet",
        default: true
    } ]

We need to account for the drug form vs the unit quantity: mg vs tablet?

My bad, basing on the data model, dose.value is expected to be numerical which means we can’t combine the quantity and units as one string, however we still need to account for the drug’s form (in inventory). Ideas??

@ibacher @burke

You really want the MedicationDispense object from core 2.6 for that. It has a quantity and quantityUnits field, modelled on FHIR…

Is the suggestion here that we want to actively be driving what gets ordered by the clinician based on inventory?

The drug form is provided in the formulary (drug table) – i.e., strength and dosage_form from OrderTemplate.drug.

We have at least four scopes for drugs:

  • Orderable drugs: Drugs in the concept table.
  • Formulary: For now, we only support one formulary (entries in the drug table). In the future, we would ideally have attributes in the drug table to support more than one formulary.
  • Drug inventory: determined by a drug inventory module or an integrated pharmacy inventory system.
  • Drug orders with templates

We should support ordering of any orderable concept, encourage ordering from the formulary, provide inventory information when available, and make ordering drugs easier with order templates.

1 Like

A drug order has a couple of coded props driven by through concept-sets. Today let’s talk about quantity units. I have two concerns:

  1. The drug order form has provision for capturing quantity dispensed but no provision for capturing “quantity unity”, How do we plan to capture this datapoint?

Screenshot 2022-08-02 at 23.29.18

  1. @akanter do we have an existing concept set for drugOrder.quantityUnits prop?

cc: @mseaton, @ddesimone

Yes, I would think it needs to be added. I don’t think the dispensing units can be inferred from the drug formulation (or dosing units), but I am not sure. Defer to any pharmacy/clinical experts here.

Also note that the drug ordering widget that PIH is using currently definitely has this:

1 Like

Quantity dispensed definitely needs units. The simplest option is to use the drug form (e.g., tablet, capsule, inhaler, etc.); however, some drugs are dispensed in other ways (e.g., package, bottle, etc.). Ultimately, we would like formulary (entries in the drug table) not only to have possible dispensing forms, but also have common dispensing amounts. For example, it’s very helpful to be able to tell a provider ordering a medication dosed as 15 mL twice daily that it comes in 450 mL and 900 mL bottles.

We should at least provide the dosage form (from drug table) as a dispensing unit option. If we have a concept set for generic dispensing units (e.g., package, bottle, etc.).

I’m unfortunately just catching up on this thread. I’d love to see where we are now. I do think it matters what the templates are based on… either a dispensable unit or a clinical unit. For example, I just started on HCTZ/Trimterene 37.5mg/25mg 1/2 tablet by mouth per day. How should that be prescribed if we don’t include dose quantity (number of tabs/caps taken at a time)? I also understand that dispensing quantity is another count of pills/tabs which should be calculable using dose/quant/freq/duration.

So there are really two conceptual processes: 1) document the clinical SIG that the drug should be taken and 2) reconciling that clinical SIG to something which can be dispensed. One is the purview of the clinical EHR and one the pharmacy dispensing system. Knowing what we should incorporate into OpenMRS with or without a link to another system seems to be a challenge.

Dose = 0.5

Dose Units = tablet

@akanter dose quantity should allow decimal (be “precise”). The data model uses a double datatype, since you can, for example, prescribe 0.5 tablets.

Good catch. Updated.