Wiki Spaces


Get Help from Others

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


Page tree

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Added a link to the demonstration module.


This is a stub page that needs to be filled in

Table of Contents




Table of Contents


OpenMRS provides Obs and objects through the API. An observation is a single unit of clinical information. Multiple observations are collected and grouped together into one encounter, which is a visit. Observations within an encounter can be grouped in a hierarchal fashion. An Obs is collected on a Patient and is given a unique identifier. Each Obs is given a date and time when it is created, as well as a location.


An Obs object is a single unit of clinical information. It represents the information that can be collected on a Patient.

Properties on an Obs:

  • obsId: the database's integer used to identify the object.
  • concept: the coded value/name given to an obs when it is made.
  • obsDatetime: the time this Obs took place.
  • accessionNumber: a unique identifier assigned to each Obs.
  • obsGroup: the "parent" if this Obs, and the grouping that brings other Obs together. 
  • groupMembers: a list of Obs grouped under this Obs.
  • value_____: various values saved from a given Obs. See more here.
  • comment: the comment written in an Obs.
  • person: the Person this Obs is acting on.
  • order: the order of an Obs.
  • location: the location this Obs took place (was taken).
  • encounter: what obs are collected and grouped together into. An encounter is a visit.
  • previousVersion: a reference to the last known version of an obs (if it has been updated).
  • interpretation: the enumerations related to the current state of being of an Obs (e.g. NORMAL, ABNORMAL, LOW, HIGH, etc.).

Code Block
// Gets Obs object matching given obsId.
public Obs getObs(Integer obsId);

// Gets Obs object given a valid UUID.
public Obs getObsByUuid(String uuid);

// Get the revision Obs for the initial Obs.
public Obs getRevisionObs(Obs initialObs);

// Saves an Obs to the database. Includes changeMessage explaining why an Obs is being changed, or is nullable if it is a new Obs.
public Obs saveObs(Obs obs, String changeMessage);

// Voids an Obs. Equivalent to deleting an Obs.
public Obs voidObs(Obs obs, String reason);

// Unvoids an Obs. Essentially "revives" a deleted Obs.
public Obs unvoidObs(Obs obs);

// Completely removes an Obs from the database. Should typically not be called in order to not ever lose data.
public void purgeObs(Obs obs);

// Gets all Obs for the given person, sorted by obsDatetime ascending. Does not return voided Obs.
public List<Obs> getObservationsByPerson(Person who);

// Gets Obs according to the criteria in the given arguments. All arguments are optional and nullable.
public List<Obs> getObservations(List<Person> whom, List<Encounter> encounters, List<Concept> questions, List<Concept> answers, List<PERSON_TYPE> personTypes, List<Location> locations, List<String> sort, Integer mostRecentN, Integer obsGroupId, Date fromDate, Date toDate, boolean includeVoidedObs,String accessionNumber)

// Searches the obs table based on the given searchString.
public List<Obs> getObservations(String searchString);

// Get all nonvoided Obs for the given patient with the given concept as the question concept (conceptId).
public List<Obs> getObservationsByPersonAndConcept(Person who, Concept question);

// Get a complex Obs. If obs.isComplex() is true, then returns an Obs with its ComplexData. Otherwise returns a simple Obs.
public Obs getComplexObs(Integer obsId, String view);


Code Block
Obs obs = Context.getObsService().getObsByUuid("1234-56789-123");
obs.setObsDateTime(new Date());
Context.getObsService().saveObs(obs, "Date Changed");

The Obs class source code can be seen here.

The ObsService class source code can be seen here.

A module demonstrating how to use this class can be seen here.

Complex Obs

See Complex Obs Support


This is a class diagram for the Obs class described above. 

Image Added

Future updates to this visualization can be made on here, or using the XML file here.