A plain-language reference for product folks scoping work that touches order entry in the O3 patient chart — medications and lab/test orders. The doc walks through the experience end to end: what the clinician does, what O3 sends to the backend, what gets validated and saved, and where the data ends up downstream (pharmacy, external systems via FHIR).

Audience: Product managers, designers, and analysts working on O3 medications, orders, or pharmacy. Engineering teammates can use this as a jumping-off point but should consult the codebase for implementation details.

1. What the clinician can do in O3

In the O3 patient chart, a clinician working with a patient's medications or lab orders has four actions available. Three of them appear as menu items on each existing order (Modify, Discontinue, Renew); the fourth is "place a new order" via the order basket.

Renew is the action with the most surprising end-to-end behavior, so it gets its own section. The rest of this doc covers what's common to all four (validation in Section 2) and the renewal-specific story in Section 3.

Medication orders can also be scheduled to start in the future. Future-start medication orders appear in an Upcoming Medications section until their scheduled start date passes, at which point they move into the active medications view.

1.5 A note on care settings

Several rules later in the doc are scoped by care setting — the clinical context an order belongs to. The default OpenMRS configuration ships with two care settings: Inpatient (e.g., a hospital ward stay) and Outpatient (e.g., a clinic visit). Implementations can define their own — for example "Emergency Department" or "Ambulatory Surgery" — via the system configuration layer.

For PM scoping, three things are worth knowing:

• The "outpatient quantity & refills required" rule (see Section 2.5) only fires for orders placed in an outpatient care setting. Inpatient orders aren't subject to it.

• The "no two active orders for the same drug" check is scoped to a single care setting. A patient can have an active inpatient Paracetamol prescription and an active outpatient Paracetamol prescription simultaneously without the system flagging a conflict.

• A renewal can't change the care setting. If a patient transitions from inpatient to outpatient, the outpatient prescription is a fresh new order, not a renewal of the inpatient one.

2. What gets checked when an order is saved

When the clinician saves the order basket, O3 sends each order to the OpenMRS backend, which runs validation before persisting. If a rule fails, O3 surfaces the error message back to the clinician and the save doesn't go through. The rules fall into a few groups.

2.1 Required fields (always)

The clinician must provide all of these. Missing any one of them blocks the save with "Cannot be empty or null."

Several of these are handled automatically by O3 (patient, encounter, orderer come from chart context) so the clinician rarely sees errors on them. The fields they typically see errors on are urgency, the orderable, and any drug-specific fields below.

2.2 Sanity checks on the dates

OpenMRS stores two date concepts that product teams should keep separate:

• dateActivated: when the order record is activated in OpenMRS. This cannot be in the future.

• scheduledDate: when a scheduled order should clinically start. This is only valid when urgency is ON_SCHEDULED_DATE.

For medication orders in O3:

• Past and same-day starts are posted as dateActivated.

• Future starts are posted as scheduledDate with urgency ON_SCHEDULED_DATE.

• Active-medication revisions cannot be scheduled for a future start. They must start today or earlier because the backend stops the previous order immediately before the replacement order's dateActivated.

The backend still enforces these date rules:

• dateActivated cannot be in the future.

• dateActivated cannot be after the stop date.

• dateActivated cannot be after the auto-expiry date.

• dateActivated cannot be before the encounter date.

• If urgency is ON_SCHEDULED_DATE, scheduledDate must be provided.

• If scheduledDate is provided, urgency must be ON_SCHEDULED_DATE.

2.3 Consistency checks

• The encounter must belong to the same patient as the order. (O3 sets these from the same context, so this only fires on data corruption.)

• If urgency is "on a scheduled date," a scheduled date must be provided. If a scheduled date is provided, urgency must be set to "on a scheduled date."

• If the order is part of an order group (multiple orders saved together), the group's encounter and patient must match the order's.

2.4 Drug-order-specific rules

Drug orders have additional rules on top of the ones above.

For simple dosing (the default), the clinician must also fill in dose, dose units, route, and frequency.

For free-text dosing (where the clinician types instructions like "take with food twice daily"), the instructions field is required.

2.5 Rules that depend on configuration

Some rules are turned on or off via system-level settings. Implementations can change these without code changes.

• Outpatient quantity & refills (default: required): for outpatient drug orders, quantity and number of refills must be filled in. Implementations that don't manage outpatient dispensing can disable this.

• Drug formulation requirement (default: off): if turned on, the clinician must pick a specific drug formulation (e.g., "paracetamol 500mg tablet") rather than just a generic concept ("paracetamol"). Off by default because many implementations don't maintain a full drug formulary.

2.6 Rules with missing translations

A handful of edge-case rules have error keys defined in the system but no English translation registered, so if they fire the clinician sees a raw key like Order.error.orderEncounterAndOrderGroupEncounterMismatch instead of a readable message. These are rare to hit in practice but worth knowing if your team gets a confused user report.

3. Renewal end-to-end

Renewal looks simple in the UI but has a few product-important details because it creates a new order that points back to the order being continued.

3.1 The clinician's experience in O3

1. The clinician opens the patient's medications list in the chart.

2. They click the overflow menu on an active medication and choose Renew.

3. The order basket opens with a basket item pre-filled from the original prescription: drug, dose, route, frequency, duration, instructions, quantity, and related fields.

4. The clinician adjusts whatever needs changing, including the start date.

5. They save the basket.

3.2 What O3 sends to the backend

When the basket is saved, O3 sends the medication renewal as action = RENEW and includes previousOrder, which points to the original prescription.

The start-date fields follow the same model as new medication orders:

• If the selected start is today or in the past, O3 sends dateActivated.

• If the selected start is in the future, O3 sends scheduledDate and urgency = ON_SCHEDULED_DATE.

3.3 What the backend does with it

1. Saves a new order linked to the original through previousOrder.

2. Does not automatically stop the original order. The original keeps running until it expires or is discontinued separately.

3. Runs the standard validation rules from Section 2.

4. Allows the renewal to coexist with its direct previous order. For unrelated active prescriptions of the same drug, the system still blocks overlapping schedules with the duplicate-active-order error described in Section 5.

3.4 What's allowed to change on renewal

If a clinician needs to switch to a different drug, that's a discontinue + new order, not a renewal.

3.5 What this means for the rest of the system

1. Renewals are distinguishable in the OpenMRS order action.
   O3 now sends RENEW to the backend for medication renewals, with a previousOrder link to the original prescription. Reporting that reads OpenMRS orders directly can use those fields to distinguish renewals from unrelated new orders.

2. Same-day renewal is still allowed.
   A clinician can place a 7-day prescription in the morning and renew it in the afternoon. The system saves both, leaving the original to expire naturally unless it is discontinued separately.

3. Pharmacy and integration behavior still needs product validation.
   Any downstream product that needs to show continuity, prevent double-dispensing, or analyze renewal chains should verify whether it reads action and previousOrder from the OpenMRS REST representation or whether its integration layer drops that relationship.

4. Implications for adjacent products

The order-entry behavior above matters for reporting, FHIR consumers, and pharmacy workflows.

4.1 Reporting and integrations should preserve renewal links

Medication renewals are represented in OpenMRS with action = RENEW and a previousOrder link. Consumers that need continuity analysis should preserve both fields. If a reporting pipeline, FHIR mapping, or analytics extract only carries the standalone medication request without the previous-order relationship, renewals may still look like separate prescriptions downstream even though OpenMRS itself has the link.

If a stakeholder asks "can we report on chronic medication continuity?" or "can we measure adherence across renewals?", confirm which data source they plan to use and whether that source exposes the renewal relationship.

4.2 Pharmacy needs awareness of overlapping and future-start orders

The pharmacy app should be explicit about whether a prescription is active now, upcoming, renewed from a prior prescription, or overlapping with another prescription for the same drug.

Two product risks to watch:

• Double-dispensing: if a clinician renews a prescription before the original is discontinued or expired, pharmacy users need enough context to avoid dispensing duplicate supply.

• Future starts: an upcoming prescription should not be treated the same as one that is active today.

Both are addressable, but require pharmacy-side workflows to read the order schedule and renewal relationship rather than treating each prescription in isolation.

5. Common errors and what they mean

A short reference for triaging support tickets or stakeholder questions where someone has quoted an error verbatim. Not exhaustive — the ones below are the errors most likely to surface in real conversations. For the full validation matrix, see Section 2.