Drug dispense and administration in OrderEntryUi

Hi everyone !

We (@mksd and I) are now starting to dig into the medication order functionality of OpenMRS, and with it the medication dispense and administration.

In this post, Options for OpenMRS drug management @burke mentions that there is 3 functions to tackle:

  1. order
  2. dispense
  3. administration

Looks like point 1 and 2 are addressed by the OrderEntryUi module. (thanks @darius !) Is there any existing module out there to especially handle point 3 ? Or did anyone start to work on anything on this topic ?

If nothing viable is done yet, then we are willing to develop a simple and straightforward solution (I guess on top of OrderEntryUi) to address basic needs in dispense and administration of medication.

@darius, is there a roadmap for the developpment of OrderEntryUi ?

Administration and Dispensing

I worked on Med Administration during the Ebola project that ThoughtWorks and some OpenMRS volunteers did with Save The Children. It’s not part of the reference application, and it’s built for a particular workflow, but you might find it instructive. Read about the project here (you can see the screens to record Med Administrations from the tablet UI, and then you can review all the administrations from the laptop UI), and the code would be here.

In that code, see “ScheduledDose” and related; we originally intended to pre-create scheduled doses that were intended to be given during a round through the red zone, and have providers check off the specific dose when administered (so we’d also know about missed doses) but we didn’t end up getting this far. However that’s why the domain object is named and design the way it is.

You said “administration” first, but then later also dispensing. I’m not sure if you’re thinking inpatient, outpatient, or both. PIH has a dispensing module they use in Mirebalais. Its lives in OpenMRS’s github here, but I think it ended up being built more site-specific (and this was really implemented as an HTML Form on top of OpenMRS 1.9.x IIRC). The dispensing records are stored as obs groups in this module. If you’re thinking of doing both Administration and Dispensing, you’d probably prefer to introduce new domain objects for these, via a module.

If you share some mockups of the dispensing and administration screens you plan to build, I’m sure people will be happy to comment on these, and collaborate on the modeling under the hood, so we end up with a module that can be reused and further extended across the community. Would you be open to joining one of our Monday/Wednesday Design Forums once you’re ready to get into the weeds of the design?

Order Entry UI Roadmap

As far as a roadmap for Order Entry UI, no, I don’t think I ever wrote anything down (I was in the middle of some heavy refactoring to support letting you embed pieces of the UI into a more complete Visit Note UI, but I assume you’re looking at using the “plain” version that plugs into the vanilla reference application.)

My recollection is that it’s “95% complete,” though it hasn’t had any real-world testing. Except for one really annoying bug that I could never figure out. The autocomplete widgets for choosing a drug, an order frequency, etc, do not work correctly when you go into edit mode (e.g. it shows the right display text, but the model is null) which is a showstopper. (I think the relevant widgets are around here.)

This is a showstopper, because it either leads to people losing data, or just having to re-enter everything each time you edit (and I think this happens for REVISE too). I had reached the point of giving up on trying to do this autocomplete on top of angular-ui’s ui-bootstrap typeahead widget, and my next step was going to be to pick some other library to build on top of. But please try debugging yourselves, and hopefully you quickly succeed at fixing this where I couldn’t!

I’m excited to see Order Entry moving forward. Order Entry is a requirement for I-TECH Haiti in the very near future. If there is anything that we can do to help (especially feedback on design or testing) please let me know.

1 Like

@arbaughj one thing you can do already is to download the existing module, add it on top of the reference application (with CIEL dictionary), and give some initial feedback on (a) whether the workflows make sense to you, and (b) what bugs you find.

Download this, and rename it to .omod http://mavenrepo.openmrs.org/nexus/service/local/repositories/snapshots/content/org/openmrs/module/orderentryui-omod/1.0-SNAPSHOT/orderentryui-omod-1.0-20151027.100824-156.jar

Thank @darius for your suggestion!

I downloaded and installed the module. It adds a “Prescribed Medications” section on the patient dashboard. When I click on it, it shows the page (with 2 tabs; Outpatient, Inpatient) where I can search for the drug name. When I search for the drug name, I don’t get any results. No error messages are given. I’m using CIEL dictionary and CIEL drugs, and obviously I’m searching for drugs that exist in my dictionary/drug list. Any suggestions?

Strange. Do you get any JavaScript console errors?

-Darius (by phone)

No @darius, no JavaScript console errors either.

FYI: I’m trying it with the OpenMRS 2.3.1 Standalone.

Hi @arbaughj,

It is the Concept Drugs that are listed (and not Concepts of class ‘Drug’, CIEL or not), you need to add them through the admin UI:

Bear with us regarding this module, we are currently gathering requirements and will start active development on it in the course of next week. (See Steps for getting started implementing OpenMRS? - #25 by darius)

Thank you @mksd. I do have drugs (From CIEL) which I imported, and they are visible under Manage Concept Drugs like you say. When I try to search for the drug to prescribe, I don’t get any results.

I’m glad you’re working on this important task!

You mean that importing the CIEL CD would also import a whole bunch of Concept Drugs? This was definitely not the case for us but we used a version dating from June or July.

As for the auto-complete not showing up what’s expected, @mksrom is telling me that you could maybe try a re-index of your database: I also seem to remember that you would need to type in at least 3 characters for the auto-complete to get triggered.

Thanks @mksd.

The drugs are a separate download from the CIEL dropbox.

Rebuilding the search index did the trick! I can now search for, find and prescribe drugs. Thank you @mksrom!

This is great! Here are a few initial thoughts (in no particular order)… 1.) It need some internationalization; translation to French/Haitian Creole. If it’s put into Transifex it can get translated. 2.) It would be nice if the auto-complete fields would show the complete list of options when initially clicked into, and then the list filtered based on what is typed. Some of the field options are short and wouldn’t require any typing then. 3.) Fix the bug with data validation. If you start to fill out the “standard dosing”, and then switch to “free text” it gives an error something like > “‘DrugOrder(1.01608 of Amoxicillin 250 MG Oral Capsule from null to null)’ failed to validate with reason: durationUnits: Durations units is required when duration is specified”. 4.) Way to add standard regimens, like for HIV care. Similar to the way the MDR-TB module or the legacy UI (pre OpenMRS 1.10) handles regimens. 5.) Quick picks for standard dosing. Automatically populate the number of pills, etc based on age/weight, and then let you edit it. 6.) Make it easy to prescribe medication while on the Visit Note. Perhaps show same prescription fields in Visit Note, or at least a one-click link to go to the order screen, ideally showing the diagnosis the doctor has just added. 7.) Integrate drug allergies to warn/block if you prescribe a drug the patient is allergic to. 8.) Make it automatically know if the patient is Outpatient or Inpatient based on Admission/Discharge encounters in current visit. 9.) Way for doctor to prescribe in the clinic, but be dispensed at another location (pharmacy). Additional details on dispensing; alternative dosage, alternative number of days, etc. 10.) Way to mark if drug was prescribed (Rx) or Prophylaxes. 11.) If the drug is marked as a capsule or tablet (in the name), I should’t have to specify it again in the prescription.

Thanks again @mksd for all of your help!

[quote=“arbaughj, post:11, topic:4212”] The drugs are a separate download from the CIEL dropbox. [/quote] I didn’t know that. Thanks. We’ll download it.

That is a clear and detailed report. Thanks :slightly_smiling:

On first thought:

1/ [quote=“arbaughj, post:11, topic:4212”] If it’s put into Transifex it can get translated [/quote] How to do that ? Would you have an example in other modules ?

2/ Seems doable 3/ Can do too. 4/ Could you tell us more about the “regimen” ? What is it exactly ? 5/ Need to check how the drugs are recorded. 6/ Good idea. 7/ Essential. The thing is to get to link the drug allergy with the drug prescribed. Need to look into that, but as a first step, at least add a little “Drug allergy summary” somewhere on the screen. 8/ Yes 9/ That was something we wanted to do from the beginning since our client do have a pharmacy to dispense drugs. 10/ Not sure to understand what it is. Could you explain me more this point ? 11/ OK, we could try to add a little code to automatically complete (or suggest to complete) the appropriate fields based on what’s in the name.

We will have a round of feedback end of this week, with better client requirements. In the mean time, I’ll investigate in more details the points above.

Thank you Romain

Thanks @mksrom for your feedback.

Concerning 1 - Transifex Translations - Most all of the Reference Application UI related modules (Like Registration) are setup in Transifex. Find more info here… https://wiki.openmrs.org/display/docs/Maintaining+OpenMRS+Module+Translations+via+Transifex

Concerning 4 - Standard Regimens - This is usually specific for HIV or TB where you put a person on a group of medications and expect them to continue taking the meds until you tell them to stop. See how it worked in the legacy UI at… https://wiki.openmrs.org/pages/viewpage.action?pageId=42041389 and https://wiki.openmrs.org/display/docs/Administering+Drug+Regimens

Concerning 10 - Rx/Prophy - My guess is that Rx would mean it’s meant to treat something, and Prophy would mean it’s to prevent something. I’ll need to look for more info on what this means on our existing form.

Thanks so much for your work on this.

Ok we showed orderentryui to our client and we have some feedback! What you will find below is a wish list, that is pretty much settled as our requirements with them.

So @darius (and others), please step in now if you find that the requirements are getting out of line as per what should happen in your opinion. Your comments/critics will be most welcome.

1. Workflow

The workflow should plug to the visits workflow and encounters of various types should thus be generated:
  • Prescription encounters
  • Dispense encounters
  • Administration encounters

This means that nothing could be done if there is no active visit, even for an outpatient. It also means that the current page should be provided both patientId and visitId parameters. When loading the medication orders for an ended visit, then the page would become read-only.

1.1 Several, grouped, order lines make a prescription order

Each prescription order is made of several order lines (one per drug basically), that is what we are seeing right now when lines are added to the prescription. In OpenMRS terms it seems that each order line is in fact a 'drug order'. Therefore each prescription order (which is a concept/object yet to come or to be pinpointed) is a group of drug orders.

Additionally there should be a way to create several prescription orders during one visit.

1.2 (Oupatient) The dispense occurs later, and is made by someone else

This has been noted by @arbaughj already and we have the same requirement. The basic idea if the following:
  1. A physician creates a prescription order at some point.
  2. A pharmacist dispenses it at a later point.

Two users with different privileges will thus access the page to perform a different set of actions.

1.3 (Oupatient) The order info may stick after the visit has ended

Even though the visit during which the order was made has ended, order lines that are still active should remain visible until the dispense period is over. Example: A visit happens on a Monday and paracetamol is ordered during the visit to be taken until the next Friday, so for 5 days. Well even though the outpatient visit is ended on the day (Monday), and the paracetamol was dispensed before that, the order line should remain active, and visible where applicable, until Friday.

1.4 (Inpatient) Administration screen

We are not yet settled at all about how to put together the administration table/page/screen/fragment/... But what we know already is that each administration event is in fact a double event since it has to be double checked. Example: Say that an inpatient prescription order states that 2ml of some drug should be administrated every 30 min for 6 hours. A nurse administers it through an 'administration encounter' each time, but then another double check event must take place: a physician will sign that the administration occurred as expected. So those (yet to come) administration lines will have several states, at least 3:
  1. Nothing done yet.
  2. Administration done.
  3. Final signature given.

2. Visual & user interface

2.1 'Active' vs 'Past' --> 'Active' vs 'Discontinued'

Active order lines should be clearly visible at the top, as they currently are already. However the below section should only show *discontinued* order lines: those that have been hit with the cross (x) button.

2.2 Order line revisions should be accessible from the order line, but hidden by default

Rather than having past revisions always visible at the bottom, they should not be visible at first. However an order line with revisions should provide some sort of link or mechanism to see the stream of past revisions. Maybe a popup? So Angular wise, we would need to design an 'order line widget', that carries its current data as well as its revisions's data. This widget would be added either to the top area when the order line is active, or to the bottom area when the line has been discontinued.

2.3 The page is made of prescription orders

There would be the need for a 'prescription order widget', with a top section for active order lines, and a bottom section for discontinued order lines, as said in the previous point. The page would then be made of a list of prescription order widgets.

2.4 'Reason' not visible, and other messages

At the moment, when discontinuing an order line, a reason must be provided. However that reason is not visible anywhere after that. This should be corrected and links us back to the need of an order line widget that should know when some additional message would have to be displayed. It could be a discontinuation reason, or any reason that led to a revision (when looking at the revision of an order line).

2.5 Concept Drugs's defaults should be filled in

'Dosage Form', 'Strength' and 'Route' should be picked up from the Concept Drug's definition and filled in upon loading the drug.

@mksd, I am excited to see the overlap of needs between your work and mine.

Would it be possible to integrate regimens (groups of drugs commonly prescribed together) and default doses (fields pre-populated for number of pills, times / day, etc) into what you’re doing?

I hope @darius and others will be able to give you valuable feedback so you can keep moving this forward to ensure best practices and be most beneficial to the community.


I wonder if that is not what is behind ‘order sets’ in OpenMRS. If yes then I suspect that another module should be brought in: openmrs-module-orderextension See more about it and the ideas behind it on

This is not currently a requirement for us but we shall keep in mind, while developing, that some mechanism will have to plug in there to fill prescription orders at once based on order set definitions. Something along those lines, if my understanding is correct.

You mean as in what is set when defining the Concept Drug? If yes then indeed we want that too and I will edit my post to reflect this…

Thanks @mksd! Thanks for the useful links. Order Set and Order Template sound like exactly what we’re needing to do.

order set – an order set represents a pre-defined list of order templates to be used in certain situations (e.g., pre-defined drug regimens, a set of common orders for treating viral gastroenteritis, etc.) order template – an order template represents a single, pre-defined order, which may include choices and/or defaults for the various components of the order. Templates allow providers to generate structured orders quickly by picking a template from a list or changing only one or two components without having to manually complete every component of the order.

Keep up the good work!

@mksd, sorry for the slow reply; pretty busy these days.

It would also be good to discuss this on a design call with @burke and @jteich soon.

Some thoughts:

I’m not sure about your usage of “prescription order”. Yes, each “order line” is a single (Drug) Order in the data model (or you might think of the line as a sequence of an order+revisions). The data model doesn’t support this yet, but you should be able to choose an Order Set and thus place several related orders together in one Order Group.

You may place multiple orders in a single encounter, and I’d think this is approximately the same as what you are calling a “prescription order”. In the UI as I had written it, this is represented by clicking the Sign And Save button a single time after writing 1+ orders.

However I think “prescription order” would be confusing terminology, because it sounds like a synonym of a “drug order”. You might call it just a “prescription” if it corresponds to everything that was ordered together in one order session, and either printed together on one sheet, or sent off to an external system in one transaction.

@jteich has described to me the idea of an “order sheet” (which lists all the orders placed in a particular encounter), and maybe this is equivalent.



I don’t have a lot to say about this. Perhaps @jteich can comment on how the med administration screen typically flows in a US/European EMR system.

I don’t understand why you would only want to display discontinued orders and not expired ones.

It makes sense that the initial view should only show the latest version of an order-line-with-revisions. I think “expand/contract” would work better than a popup.

I don’t like this (at least, not as I’m understanding it). It sounds like you’re saying that drug orders should be grouped/sorted based on being ordered together, and thus if you read the page from top to bottom you might see some active orders, then some discontinues ones, then more active ones, then more discontinued ones. This sounds completely wrong to me. I think the primary view should have all active orders on top, above anything else. There can be secondary views to show you what was ordered together.

Take a look at how we grouped/displayed orders in the Ebola system we built (see om.rs/ebolademo and feel free to write some prescriptions and see how it behaves; some code here). @jteich and I put a good amount of analysis into grouping by generic (i.e. order.drug.concept) and then sorting based on most recent activity on the order.

Another thing worth looking at is the “Order Sheet” that I was building for PIH last year. Here is the angular directive.

I agree that it should be possible to see all the data. IIRC we did a better job of this in the Ebola system, where we actually grouped orders by their orderable.

As much as possible, choosing a drug should automatically select default values for fields. But keep in mind this isn’t 100%. An ampule usually means IV or IM, but could also be given orally, or nebulized. A drug that is a “500mg tablet” can be equivalently ordered as “1g” or “2 tablets”.

The code includes the beginnings of the ability to do this. See inferFields which assumes your concepts have mappings to SNOMED CT codes.

Hi @darius,

(@mksd I hope you don’t mind if I reply, I know you are pretty busy in the next coming days)

Could you explain me more the Order Set / Order Group and how you would see it fit here ? Or wouldn’t it be lighter to add a new field in the data model ? Something like a ‘revision_order_id’ in the ‘orders’ table (containing a reference to the ‘order_id’ that is revised).

OK. Now looking at the code in Order Entry UI, I see that it already creates an encounter when click on Save & Sign, which is great (we have less to do !).

        // HACK
        EncounterType drugOrderEncounterType = encounterService.getAllEncounterTypes(false).get(0);

I guess we just have to replace this to get the right Encounter Type.

That sounds perfect to be used as a ‘Prescription’ document.

I recall that another reason we had in mind for using an encounter to group all orders, is to keep the orders associated with a VisitId. What do you think on that point ?

Well, I think we didn’t know/think about the expired ones yet. :confused: So I guess there would be 2 sections within the ‘Past Orders’ section: expired ones and discontinued ones.

There is a lot of interesting stuff here ! And I see IV fluids as well. But unfortunately I can’t create new prescriptions. I get a blank screen when I click on any pen button (any widget):

Any idea why ? Is it because of Tablet vs Laptop UI or something ?

Again, thanks for showing us that. That will come usefull later I think because we may need to display orders by encounter in some medication dashboard or report.

In the OrderEntryUI module, how is the dispense event saved and how is it linked to the drug order ? And in the Ebola distro ? What would you suggest here ?

Definitly. When would be a suitable time for you ?

Thanks again. Romain

You can ignore what I wrote there, as long as you’re okay with the concept that what you’re calling a “prescription” is “all the orders in one encounter”.

I agree with the spirit behind this (i.e. you only place an Order for a patient who is present).

In the underlying API, every Order must belong to an Encounter, but not every Encounter must belong to a Visit, so it doesn’t technically work as you say, and the UI code shouldn’t assume this. But if you also set up other workflows so that in your implementation all encounters have visits, then things will work like this.

I think I understand our miscommunication. IIRC I wrote that UI to show all past orders, but you are right, it should probably be done in such a way that only a single row is shown for the entire “thread” of a past order. E.g. if an order was placed, then revised, then discontinued, this should be just one row (probably expandable). I would keep expired and discontinued together in the same place, as having multiple tables doesn’t make clinical sense AFAIK.

However, it may be better to take a completely different approach, which is what @jteich had me do in the Ebola application that we built after the orderentryui module you’re looking at. Instead of dividing “active” vs “past”, instead it’s a single list where each list item is a group of everything that ever happened for one Drug. Internally, each group is sorted by “most recent thing to happen” at the top. The groups are sorted relative to each other based on “most recent change for any drug order for the group’s drug”.

This is what Jonathan asked me for:

And my implementation looked like this:

(this is specifically showing that the most recent thing to happen was that Albendazole 400mg expired, so it is shown at the top, even though there are other drugs still active below it (but their “activity” is less recent).

If you want more details about this approach, contact me by email and I will forward you a long email chain where we discussed this and sent screenshots back and forth.

(Sorry, the tablet UI of the Ebola demo seems to be broken, with some Angular error. I have no idea why, and no time to debug now.)

The OrderEntryUI module doesn’t do dispensing or administration at all. See my message earlier on this thread (message 2) about dispensing in a PIH module and administration in the Ebola system.

@jthomas, can you please work with @mksrom to get this on a Design call? (Ideally @burke and @jteich will both join too; we can probably live with having just one of them if scheduling is difficult.)