Wiki Spaces


Get Help from Others

Q&A: Ask OpenMRS
Discussion: OpenMRS Talk
Real-Time: IRC Chat | Slack


Page tree
Skip to end of metadata
Go to start of metadata


First came the encounter...

One of the first resources added to the OpenMRS data model was the "Encounter." When it was added, the Encounter was designed to be the electronic corollary to the paper encounter forms being used by implementations. A patient would come to an HIV clinic, data was collected on a paper encounter form, and these data were transcribed into OpenMRS as a collection of observations grouped within an encounter.

Then came the visit...

Somewhere around 2008, we had a conversation at an OpenMRS Implementers Meeting about the need for a more flexible model to allow for more than paper form to be collected when the patient came to clinic. We also knew that the existing one-encounter-per-paper-form approach was going to fall short as people started using OpenMRS to record hospitalizations. At that meeting, we came up with a more flexible design:

  • Encounter would represent the clinical transaction between the care system and patient (e.g., the provider seeing the patient, documentation of a telephone call, vitals and other data collected by a triage nurse, etc.). Basically, it wouldn't change much from the point-in-time "transaction" for which paper encounter forms were used.
  • Visit would be added to represent the actual "visit" to the provider over a period of time (hours, days, weeks, or more). A visit could contain one or more encounters. This would correspond to a clinic visit, but could also easily represent a entire hospitalization or virtual visit (like a telephone visit).
  • Episodes of Care would be used to link encounters across visits that were related. For example, grouping all encounters relating to a specific diagnosis or to a treatment program.

Visits were introduced in OpenMRS 1.9+. At the end of 2015, we were just starting to have enough interest & need in Episodes of Care to bring them to life.

Then came real time (ad hoc) data entry...

We felt pretty good about the model of encounters capturing the clinical transactions, visits grouping these encounters into clinic visits & hospitalizations, and the flexibility of episodes of care to organize encounters in ways other than visits. But as people started using OpenMRS more & more in real-time care, creating mobile tools for data collection, and wanting to leverage web services, we discovered a way in which our model wasn't quite complete. There was a growing tension whether encounters represent technical vs. clinical/administrative transactions. Our encounters were meant to collect data (observations, orders, diagnoses, notes, etc.) within clinically meaningful groupings, like the paper encounter form. With real time data entry tools, we saw a growing number of cases where these data were coming in piecemeal. For example, a provider would enter a few orders and observations on their phone and enter diagnoses and some additional orders for the same encounter later or through a different tool. When we group the collected data to make the developers happy (in the technical transactions as data arrive), the grouping didn't make clinical sense; when we enforce the clinical groupings of data into encounters, the developers sometimes end up struggling with forcing the technical transactions & workflows to match the clinical need.

Graham Grieve pointed out the FHIR distinguishes between the technical and clinical/administrative transactions (i.e., how clinicians want to group data vs. how the computer & technical workflows want the data grouped). That distinction sounded like the solution we needed... and that is what this page is about. How do we introduce a new grouping of clinical data that can represent the technical transactions?


So, we want to be able to represent technical groupings of clinical data alongside our clinical/administrative grouping (our Encounter). In other words, the same data (observations, orders, diagnoses, notes, allergy changes, etc.) that we want to continue organizing into Encounters needs to be able to collected piecemeal and we want to be able to track those technical groupings and relate them to the Encounter. Another way to think of these technical transactions is like a "session". If we use the paper encounter form metaphor, we are saying that, while a provider might complete a paper form in one sitting, we want to allow the provider to fill out the form across multiple transactions and be able to track those individual transactions.

Example Use Cases

  • A mobile device contributes an order to the encounter, a desktop app contributes a note and diagnoses, and a transcription process add some more orders, diagnoses, and observations. All of the transactions can contribute to the same encounter. The encounter represents the clinical transaction, yet we still know which data were contributed from which technical transaction.
  • A provider uses a tool to contribute data to the encounter while interviewing and examining the patient. The data are entered in chunks meeting the needs of the provider's workflow and the particular tool. Later on, all of those transactions can be viewed as a single clinical encounter without losing the information about the individual technical transactions.

Design Ideas

Encounter Transactions 1

The simplest approach would be to add a technical "Transaction" grouping to link encounter data that were delivered within the same technical transaction. Any data within an encounter could be grouped within one or more technical transactions, representing the manner in which the pieces of the encounter were contributed. Then Encounter resource would contain or be linked to any clinical/administrative metadata (time of encounter, providers involved in encounter, type of encounter, etc.) and the Transaction resource would contain any technical metadata (time data received, method of data delivery, etc.).


  • Encounter must exist (or be created) for any Transaction – i.e., a Transaction must be linked to at least one encounter.
  • We could consider allowing a Transaction to span Encounters, since a technical transaction could potentially add/alter data within more than one Encounter (e.g., a chart audit in which multiple charts are affected). This would avoid the need for additional Transaction grouping, but might make the model and API more confusing.

See Also


  • No labels