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



Clinical notes (narrative reports) are a core part of any medical record system. A "note" table was introduced into OpenMRS core early in its development, anticipating the need; however, several years passed before it became a priority for implementations. The core note table is not design properly nor has it been wired into the API. Furthermore, a project involving notifications used a Note object, which has been left unused within core.

OpenMRS needs notes (narrative text) to be a component of encounters (just like orders and observations) to accommodate clinic notes, inpatient progress notes, admission notes, discharge summaries, etc. Notes should also accommodate binary notes (e.g., scanned notes).

A clinical note within OpenMRS may be thought of as:

"Any patient-centric narrative that is not a test or procedure result and has (or would ideally have*) a plain text view."

* "ideally" is used here to include scanned documents that may only be understood as images, but ideally would have perfect OCR performed to retrieve text from them.

Notes within OpenMRS are meant for narrative text (from plain text to CDAs to scanned documents), not images like x-rays or other multimedia that are observations (i.e., complex observations).

Project Champions


  • Encounters should be able to contain one-to-many clinical notes.
  • Notes do not have to be part of an encounter – i.e., like obs, encounter should be optional.
  • Notes should have a type that is a concept or can be linked to a concept
  • Notes should be easily searchable, especially by patient.


  • Remove the existing Note object within the notifications package.
  • Adapt the note table to meet requirements.
  • Create a NoteService to manage clinical notes.
  • Allow for complex notes (like complex obs) to accommodate binary/external notes

Design Ideas

Note Data Model

  • note.mime_type – used to describe the content type (distinguish plain text from PDF from a particular XML format).
  • note.text – contains content for text-based notes, may be empty or contain indexable text for complex (binary) notes
  • note.uri – describes location of note for complex/external notes (used by handler)
  • note_type.concept_id – provides an optional mapping to a concept
  • note_type.is_complex – true if the note type requires a handler to set/get/render content
  • note_type.complex_handler – reference to Java class the implements complex handler interface

Extra Credit

  • Use built-in lucene indexing to allow for rapid searching of notes.


  • No labels


  1. Would it be useful to be able to link a note to an observation as well? 

    1. Vinay Venu, while structured notes might include references to observations, the subject of clinical notes is assumed to be a patient.

      We have envisioned something like "memo" to serve as notes that could be attached to any object (observation, patient, encounter, note, etc.) much like a sticky note might be used on a paper chart.

      1. Thanks Burke Mamlin. I was also thinking along the lines of a "blob of text/memo" that can be associated with any object. This is a very useful feature. 

        Looking at the table structure, I could not understand how we relate a note to, say another note. Usual implementations have something like an external_id and an external_id_type that denotes the related table.


        1. The assumption is that clinical documents (notes) that belong to the same clinical transaction would be in the same encounter.  To support addenda, which would occur in subsequent clinical transaction(s) (encounter(s)), we would add a relationship within encounters (e.g., addends_encounter).  Structured notes could contain links, but we're not designing for a hierarchy of clinical documents.

          Memos (as I'm referring to them at the moment) would be the small notations made on an observation, patients chart, or a clinical document.  The note table (artifact) currently sitting in the OpenMRS data model is a remnant of something closer to the memo idea.  We would definitely want these to be hierarchical to support, for example, threaded discussion.