Order Entry API Scenarios

This page is a work in progress and subject to (drastic) change.

PurposeThis page is an attempt to use stories (use cases) to drive our order entry API design. Initial use cases will focus on the more fundamental features of the order service. Subsequent scenarios can expand on desired functionality.

Scenarios

Find Orderable Concepts

Retrieve a list of the things that can be ordered that start with "AMP".

Get the List of Active Medications

Retrieve a list of "active" orders (started, but not yet ended/expired/discontinued) of a specific type (medications).

List<Order> activeOrders = Context.getOrderService().getActiveOrders(myPatient);

or

Date date = // date for 15 June, 2010
List<Order> activeOrdersAsOf15June2010 = Context.getOrderService().getActiveOrdersAtPointInTime(myPatient, date);

Also want to be able to get orders by user, by order number.

Creating a Medication Order With Unstructured Dosing

Order AMPICILLIN 500 MG AS DIRECTED.

Concept drugConcept = conceptService.getConcept("AMPICILLIN");
DrugOrder order1 = new DrugOrder(drugConcept);
order1.setUnstructuredDosing("500 MG AS DIRECTED");
try {
  orderEntryService.signAndActivateOrder(patient, drugOrder);
} catch (APIException e) {
  // deal with failure
}

Creating a Medication Order With Structured Dosing

In this scenario, we just want to add a (new) medication order to a patient's list of active orders.

Concept drugConcept = conceptService.getConcept("ACETAMINOPHEN");
DrugOrder order1 = new DrugOrder(drugConcept);
order1.setUrgency(Urgency.ROUTINE); // Not needed, since ROUTINE would be default
order1.setDose(new Dose(500, Dose.MG));
order1.setRoute(Route.PO);
order1.setFrequency(Frequency.DAILY);
order1.setDuration(Duration.INDEFINITE);
order1.setPrn("pain");
try {
  orderEntryService.signAndActivateOrder(patient, drugOrder);
} catch (APIException e) {
  // deal with failure
}

When the order is first signed, it gets a new (next available) order number.

Revise an Order

TBD

Discontinue an Order

TBD

Define a Medication Regimen

Define a regimen of two drugs that can be ordered together. For example, ATAZANAVIR 300 MG ONCE DAILY + RITONAVIR 100 MG ONCE DAILY ordered as a single HIV TREATMENT REGIMEN.

Concept hivTreatmentRegimen = conceptService.getConcept(1432); // HIV TREATMENT REGIMEN
Drug atazanavir = conceptService.getDrug(123); // ATAZANAVIR 300 MG
Drug ritonavir = conceptService.getDrug(456); // RITONAVIR 100 MG

OrderTemplate atazanavirOrder = new DrugOrderTemplate(atazanavir);
atazanavirTemplate.setDoseChoices( new DoseChoice[] { new Dose(300, Dose.MG) } );
atazanavirTemplate.setFrequencyChoices( new FrequencyChoice[] { Frequency.ONCE_DAILY } );

OrderTemplate ritonavirOrder = new DrugOrderTemplate(atazanavir);
ritonavirTemplate.setDoseChoices( new DoseChoice[] { new Dose(100, Dose.MG) } );
ritonavirTemplate.setFrequencyChoices( new FrequencyChoice[] { Frequency.ONCE_DAILY } );

OrderSet orderSet = new OrderSet(hivTreatmentRegimen);
orderSet.addMember(atazanavirTemplate);
orderSet.addMember(ritonavirTemplate);

try {
  orderEntryService.saveOrderSet(orderSet);
} catch (APIException e) {
  // deal with failure
}

Order a Medication Regimen

Order the regimen defined above (HIV TREATMENT REGIMEN) and have the individual drug orders become active orders that are linked through the regimen.