Status: REQUIREMENTS IN PROGRESS

Technical Complexity: HARD / COMPLEX

Big Picture:

• Templates are orderables. There is no "choose a template" step — one search box, no separate Drug Orders and Lab Orders search areas. A template is just another row the prescriber can pick, and order sets appear in the same list: a bundle is one more kind of result, whose members each resolve through their own template.

  • Searching returns the best way to order each thing: where a template exists, the templated result is the hit (each common regimen its own result, rendered in plain language with {blanks} for anything undefaulted) — a blank row is never shown beside it. Every result offers Add (straight to the basket — one click when complete) and Edit (the standard order form, pre-filled). Everything stays editable; nothing ever auto-signs.

  • Templates assist, never restrict: no template, broken template, or unknown type — the prescriber always gets the normal blank form. Nothing is ever un-orderable for lack of a template.

  • Templates are generic and type-driven: the same mechanism serves drug orders, test orders, and order sets, and new order types join by registering a handler.

 

Open

 

 

 

An order template provides the default (and optionally alternative) values for one common way of placing a specific order (a drug order, a test order, etc.). It assists; it never gates orderability.

• A template = a type (versioned URI) + a target orderable (drug, concept, or test) + default field values, with blanks for anything undefaulted. The type routes to an OrderTemplateHandler<TemplateType> that (a) resolves the template into a draft Order and (b) renders it as human-readable text for search results and review (e.g. metoprolol {dose} mg by mouth {frequency}). Field structure varies by type — dosing for drug orders, specimen/urgency for test orders — which is exactly why the model is type-driven rather than drug-shaped.

• Templates assist; they do not restrict. An orderable with no template must still be fully orderable via a blank order form.

• Templates are separate from the formulary. The drug table is the inventory (name, form, strength). The template is the "how it's given" layer, often authored by a different body (Ministry, clinical board, pharmacy). For test orders, the equivalent split is the test dictionary vs. the template.

Template schema

1: Simple Dosing

One convention throughout: every field — dosing and dispensing alike — is an array of {value, default} entries inside dosingInstructions. All five dispensing fields are optional: omit them and the order form leaves duration blank (a prescriber decision) and auto-computes the quantity once a duration is entered. This matches the seed payloads in §6.5 and the deployed data shape ratified in §9. (The test-order schema below is unaffected — its flat concept/urgency/instructions fields are correct for that type.)

2: Simple Test Order

Clinicians re-enter structured details for common orders (drugs and routine tests) even for the handful of ways each is almost always placed. This is slow, error-prone, and inconsistent across providers.

The community produced a backend module (openmrs-module-ordertemplates) and a proof-of-concept, but the effort stalled on modelling questions (dose/unit shape, where the domain lives, dispensing) and, critically, the initial flow made templates mandatory to order a drug — the exact coupling the community rejected. We need a documented, agreed V1 that:

• pre-fills the order form from a template when one exists,

• never blocks an orderable from being ordered,

• keeps the template vocabulary cleanly separated (SIG is a drug-only term; test orders use their own fields)

• and gives implementers a way to see and close coverage gaps.

• Common order (Amoxicillin): As a prescriber, when I search for a drug that has a template, I want the templated result to BE the hit — amoxicillin 500 mg by mouth every 8 hours for 7 days, in place of a blank row — with Add and Edit, so one click puts it in the basket, or Edit opens the pre-filled form for the exceptions.

• Several ways to order (Metformin): As a prescriber, when a drug has more than one common regimen (e.g. metformin 500 mg twice daily and 1 g twice daily), I want each shown as its own search result rather than hidden behind a picker, so choosing the right one is a single click.

• Common test order (Renal function panel): As a prescriber, when I order a routine test, I want it pre-filled and one-click through the same template mechanism as drugs — e.g. Renal function panel — routine — so templates work across order types, not just drugs.

• Uncommon order: As a prescriber, when an orderable has no template, I want a fully usable blank order form so I can still order it. Nothing is ever un-orderable for lack of a template.

• Concept default (Amlodipine): As an implementer, I want to attach one template to a concept and have it pre-fill every formulation of that concept that lacks its own, so I don't maintain a template per drug-table row.

• Free-text SIG (Diazepam): As a prescriber ordering a drug whose instructions don't fit structured dosing — e.g. a diazepam reducing course, where the dose changes day to day — I want a free-text template that pre-fills the full instruction text.

• PRN order (Paracetamol): As a prescriber ordering an as-needed drug, I want the template to pre-fill the PRN flag, the indication, and an explicit dispense quantity — because there is no treatment duration to compute a quantity from.

• Dispense quantity (Amoxicillin): As a prescriber, once a duration is set on a template-seeded order, I want the quantity-to-dispense auto-calculated (dose-form-units × frequency/day × duration) so I don't compute it by hand.

• Readable rendering: As a prescriber, I want a template shown as plain text with its defaults filled in and blanks left for anything undefaulted (e.g. metoprolol {dose} mg by mouth {frequency}) — both in search results and on review — so I always know exactly what I'm about to order.

• Coverage visibility: As an implementer, I want a report of which orderables have no template (directly or via concept fallback) so I can close the gaps for the ones I actually order.

Acceptance Criteria

1. Template resolution, rendering & defaults. Templates surface directly in search and pre-fill the order form; the prescriber edits only exceptions.

• Given ≥1 active template exists for an orderable (drug, concept, or test), searching returns each ready-made way to order it as its own result, rendered readably (e.g. amoxicillin 500 mg by mouth every 8 hours) — in place of the blank row for that orderable, not beside it. Every result offers Add and Edit.

• Add puts the order straight into the basket with no intermediate screen; Edit opens the standard order form with the template's values filled in. No template-specific screen exists anywhere in the flow.

• A template is rendered as a human-readable string with its defaults filled in and blanks shown for any undefaulted field (e.g. metoprolol {dose} mg by mouth {frequency}) — in search results and on review.

• If an orderable has several common templates, each appears as its own result (no dedicated picker required).

• Adding a template pre-fills the order per its payload.

• If no drug-specific template exists, a concept-level template is used when present.

• If no template exists, the blank order form is shown (no error) — nothing is un-orderable for lack of a template.

• All pre-filled values remain editable before sign; nothing is auto-signed.

• Clicking a pinned drug (My pinned drug orders) resolves its template through the same path (drug-level first, concept fallback); no template, missing privilege, or any fetch failure opens the blank form; repeat clicks while the fetch is in flight are ignored.

• A template that supplies every field the order form itself would require yields a basket item not flagged Incomplete — addable and signable without ever opening the form. An item missing any required field is flagged Incomplete and must be completed in the form before signing.

2. Concept vs orderable specificity.

• Templates bound to a specific drug/orderable match only that one.

• Templates bound to a concept only (no specific orderable) apply to any formulation of that concept lacking a more specific template.

• Retired templates are never returned or applied — enforced by the backend search, so the frontend never receives retired templates and does not filter them itself. (The module enforces this for V1; core order_template inherits it after the §6.6 Stage-1 migration.)

3. Order types & handlers. The model is type-driven, not drug-shaped: each template type routes to an OrderTemplateHandler that resolves it into a draft order and renders it.

• Drug, simple dosing — supplies dose, units, route, frequency, asNeeded, asNeededCondition, and patient instructions (wire key instructions — array of { value | text, default }; the default entry pre-fills patient instructions).

• Drug, free-text dosing — supplies an instructions text SIG.

• Where a schedule can't be expressed as a single dose × frequency — a changing-dose taper being the clearest case — use a free-text template carrying the whole SIG as text. (Diazepam: "5 mg three times a day for 2 days, then twice a day for 2 days, then at night for 2 days, then stop.") A minor timing note on an otherwise-simple order (e.g. "take the first dose at bedtime") rides along in the simple template's instructions.

• Non-drug (test) order — resolves through the same type → handler → draft-order path, with its own field structure (e.g. concept, urgency, specimen). Adding a new order type = registering a handler; the order basket needs no type-specific changes. (INR test order.)

• A template whose type has no registered handler is excluded from search results (logged with the template's uuid and type) — never offered, never crashes the search; the orderable's plain blank-form entry remains available.

4. Dispensing defaults.

• When a duration is present, quantity-to-dispense is auto-computed (dose-form-units × frequency/day × duration) and shown as editable. (Amoxicillin → 1 × 3 × 7 = 21 tablets.)

• When quantity cannot be computed — PRN, chronic, or a free-text schedule — the template's explicit default quantity/quantityUnits/numRefills pre-fills. (Paracetamol #100/0; Amlodipine #90/3; Metformin #180/3; Diazepam #12/0, summed across the taper.)

• Dose units and dispense units can differ (paracetamol dosed in mg, dispensed in tablets), and packaged/combination products dispense by pack or "dose" rather than by tablet — so quantityUnits is recorded on every order. (Multi-ingredient/combination products are out of the V1 seed set; see §6.3 and the deferred list.)

5. Implementer seeding.

• Seeding is via the backend REST API (or SQL) for V1. Initializer-based loading needs a domain loader — a backend task, scoped into V1 explicitly or listed as a non-goal (see §9).

• REST create/update/retire endpoints remain available for tooling.

• A documented example payload set is provided (§6.5): four simple drug templates, one free-text drug template (diazepam), and one simple test order (Renal function panel)

Major EMRs separate "the catalogue of orderables" from "pre-filled ways to order them," and none force a template to exist before an orderable can be ordered. The same pattern holds across order types — drugs and tests — which is the market evidence for a generic, not drug-specific, model.

• Cerner — "order sentences." Pre-completed order details (dose/route/frequency/PRN) attached to an orderable, selectable in one click and editable at point of order. Providers can save a modified order as a personal favourite. Cerner order sentences exist for labs and other orderables too, not just drugs — direct support for the type-driven approach. Confirms pre-fill-not-restrict and one-orderable-many-sentences.

• Epic — preference lists, favourites, SmartSets. Preference list = the browsable catalogue; Favourite = a single order saved with preferred dose/route/frequency/dispense (the per-order template analog, created by starring a real order); SmartSet / order set = a grouped bundle for a protocol. Two lessons: favourites are created from real orders ("star this order to reuse") — a strong argument for the eventual "save current order as template" authoring path; and Epic treats the single favourite and the multi-order set as points on one continuum, which is exactly the unify-on-order-sets option under discussion

• • FHIR — ActivityDefinition → a request. A reusable, patient-independent definition instantiated into a patient-specific request — precisely the template→order relationship, and it is not drug-specific: ActivityDefinition seeds a MedicationRequest, a ServiceRequest (labs/referrals), and others. Keeping our shape translatable to ActivityDefinition (and the resulting orders to the matching request types) is the north star, even though V1 stores its own JSON.

• Common threads: (1) template pre-fills, never gates; (2) one orderable → many templates; (3) templates span order types, not just drugs; (4) single templates and multi-order sets sit on one continuum; (5) templates can be institutional or personal (V1 = institutional only); (6) best authoring path is "save a real order as a template."

• Template resolution — the core abstraction. Each template type (versioned URI) routes to an OrderTemplateHandler<TemplateType> that (a) resolves the template into a draft Order and (b) renders it as a human-readable string for search results and review. Adding a new order type (e.g. test orders) means registering a handler — the order basket needs no type-specific changes. This is what keeps the design generic rather than drug-shaped.

• Templating is a service, not a search feature (Burke, squad call). The handler interface — given an orderable/order and a template, produce (a) the draft order and (b) the rendering — is consumed identically by order search, order-set rendering, and future decision-support suggestions ("offer this order"). Search knows templates exist; templates know nothing about search. Consumers never assume a template's shape: they dispatch on its type, and an unregistered type behaves as no-template.

• Storage / where the domain lives — Keep openmrs-module-ordertemplates for V1; commit to a first-class core order_template later; do not model templates as single-member order sets — order sets are one consumer of templates via order_set_member.orderTemplate / orderTemplateType. The interfaces below (handler, resolution, rendering) are storage-agnostic, so the migration lands without reworking the frontend.

• Fetch / search API. V1 needs to resolve templates for an orderable and surface them in search. Preferred direction (Ian): a single backend endpoint that interleaves orderables and their templates server-side, so the frontend stops doing per-drug template fetches. The existing module's ?drug= / ?concept= fetch works for a first increment but is the drug-keyed pattern we're moving away from.

• Orderable-set membership: a test-order template only surfaces if its concept is a member of the configured lab orderable concept set — seeding one without that makes it invisible in search.

• Feature Flag: both the medications app and the tests app declare the ordertemplates optional backend dependency in their routes.json; the flag auto-enables when the module is installed.

• Privilege: View OrderTemplates gates the template lines on drug and test search tiles and the pinned-orders template fetch; roles without it get safe blank-form degradation.

• Core deps: webservices.rest; MedicationDispense for the separate dispensing concern.

• Frontend: O3 order basket (@openmrs/esm-patient-medications-app) + shared types in @openmrs/esm-patient-common-lib. The basket resolves templates via the handler, renders them in search results, applies defaults, and allows edit. No template → blank form.

• Metadata / seeding: V1 seeds via the backend REST API (or SQL). Initializer-based loading needs a domain loader — a separate backend task, scoped in or listed as a non-goal (§9). Provide sample REST seed payloads.

6.2 Coverage: assist and measure, don't enforce

V1 does not guarantee every searchable orderable has a template — and must not try to. A constraint requiring a template before an orderable can be ordered recreates the rejected common-medication.json coupling, and can't hold in practice (the catalogue and the template set are maintained independently). Instead:

• Concept-level fallback is the primary coverage lever — coverage counted per concept, not per catalogue row.

• Guaranteed blank-form fallback (hard requirement) — makes partial coverage acceptable.

• Coverage / gap report — join the orderable/concept set against the template store, list uncovered orderables. Proposed scope: fast-follow — a pre-canned query/script, not an in-app screen (reporting doesn't belong in the order basket).

• Seed-time pairing — pair a template CSV with the catalogue/formulary CSV via the Initializer, not a DB constraint.

6.3 Clinical Content Governance

• Ownership: Each implementing site designates a clinical owner for template content (pharmacy for drug orders; the lab/clinical lead for test orders). OpenMRS does not ship a universal formulary of templates.

• Lifecycle: Create → review → activate → retire. Retired templates must not be returned by the search the basket uses.

• Naming (recommended): Include the orderable and its key defaults in the name (e.g. "Amoxicillin 500 mg PO q8h" for a drug; "Renal function panel — routine" for a test).

• Coverage: Fast-follow canned script listing orderables/concepts without an active template. Not part of the order-basket UI.

6.4 Safety & Tech Risks

• Stale defaults: A template whose dose no longer matches current formulary strength could suggest an unsafe order. Mitigation: retire on catalogue change; coverage script flags gaps; clinicians always review before sign; existing order validation still runs.

• Wrong template selection: Several templates for one orderable increase mis-pick risk. Mitigation: clear, self-describing names; render defaults (and blanks) in the search result so the clinician sees exactly what they're adding before they add it.

• Over-trust of pre-fill: Clinicians may sign without reading. Mitigation: no auto-sign; all fields visible and editable.

• Non-drug order types (NEW): As test orders join in V1, their handler must apply the same safety posture — no auto-sign, editable, validated by the relevant order service — not just DrugOrder validation.

• Patient-harm pathway: Incorrect order from a bad template. Residual risk accepted only with (a) clinical ownership of content, (b) a retire process, (c) no bypass of the relevant order-service validation.

6.6 Backend Roadmap

V1 ships with no backend changes — it consumes the existing openmrs-module-ordertemplates as-is. The frontend's template fetch is deliberately confined to one file, so every stage below lands without reworking any screen.

• Stage 1 — Move templates to their permanent home (ratified, §9 "Where does the domain live")
  Migrate template storage from the standalone module to a first-class core order_template. Per the ratified position (Burke): templates are their own domain — do not model them as single-member order sets; order sets are one consumer of templates. The migration also adds what the module never had: server-side JSON validation on save (known type URI + parseable body) and fixes the over-return bug (an unresolved ?drug=/?concept= must return empty, never all rows). During transition, either keep the module's read endpoint answering from the new store for one release, or coordinate a same-release frontend seam swap.
  Effort: ~1–2 weeks after a core design review. Owner: platform/backend.

• Stage 2 — Order-set REST readiness (§9 row)
  Audit the existing /ws/rest/v1/orderset CRUD (ships with the REST module, platform 1.12+), then close the ordering-workflow gaps: search-by-member-orderable (?orderable=<conceptUuid>), a representation exposing members with their orderTemplate payloads in one round trip, and retired-exclusion by default. Same over-return rule as Stage 1.
  Effort: days. Owner: REST module. Independent of Stage 1; needed before Stage 4.

• Stage 3 — Interleaved orderable search (Ian's preferred direction, §9 row)
  A single emrapi endpoint — GET /ws/rest/v1/emrapi/orderable?q=…&types=… — returning drugs, tests, and order sets with their templates attached: scoped server-side, retired excluded, ranked and paginated. Privilege-degrading: a caller without View OrderTemplates receives the same orderables with empty template lists, not a 403, so search never breaks for non-privileged prescribers. The template field stays a JSON string in today's stored shape, so the frontend consumes it unchanged; adopting the endpoint retires the current per-drug fetch pattern in a one-file frontend swap.
  Effort: ~1–2 weeks backend + 1–2 days frontend. Owner: emrapi module.

• Stage 4 — First multi-orderable bundle: the Hypertension order set (§9 row; Future Iterations)
  An order set whose members — a first-line antihypertensive (choose exactly one: amlodipine 5 mg default, hydrochlorothiazide 12.5 mg, enalapril 5 mg) and a baseline workup (choose any: renal function panel default, lipid profile, fasting blood glucose, urinalysis, ECG) — each carry their own template via the existing order_set_member.orderTemplate / orderTemplateType columns (Ian #44): this is precisely how order sets consume templates under the Stage-1 ruling. The frontend resolves each selected member through its registered handler into the drug and lab baskets. Selection UI per the squad-call ruling: adding a set opens its description and choice groups, and the basket fills only when the set is saved. Recurring-schedule semantics ("repeat the renal panel in 2 weeks") are explicitly out of scope and need their own design session (#46); the MVP carries any schedule as instruction text.
  Effort: ~1–2 weeks frontend once Stages 1–2 exist. Blocked only on Stage 1.