OpenMRS Basics

2019 status: Current

OpenMRS provides a large and quite complex relational data model for medical records, and a Java implementation that uses Hibernate to integrate with a few different SQL databases. Buendia deployments use MySQL.

Handy places to look for information:

• Descriptions of all the service interfaces: JavaDoc for org.openmrs.api
• Service implementations: org.openmrs.api.impl.* on GitHub
• Validation rules: org.openmrs.validator.* on GitHub
• OpenMRS Talk, where you can ask technical questions and search previous discussions

Services and models

The OpenMRS API consists mainly of service interfaces, each of which provides access to instances of related model classes. For example, there is a Person model class, and among other properties it has a birthdate accessed via getBirthdate() and setBirthDate(Date). There is a corresponding PersonService interface for getting Person objects from the database and storing them into the database, and the implementation of this interface is obtainable from the global Context object. Thus, setting the birthdate of an existing Person looks like this:

PersonService service = Context.getPersonService();

// Get a person by integer ID.  PersonService provides various
// methods for retrieving or searching by other criteria.
Person person = service.getPerson(123);

// Make changes in memory, not yet committed to the database.
person.setBirthdate(new Date(2000, 1, 1));

// The service will now validate the data, then store it.
service.savePerson(person);

The model classes and services all follow this basic pattern.

See Buendia and OpenMRS for more on how we make use of the OpenMRS data model in this project.

Database IDs and UUIDs

Every model instance ultimately ends up in a SQL table, and has a primary key in that table. The primary keys are small integers, exposed by the model class. The Person class has a Person.getPersonId() to get this integer ID, the Concept class has a Concept.getConceptId() method, and so on.

These IDs are small and convenient for the SQL database to use, but they are only locally unique. Most model classes also provide a different identifier that OpenMRS calls the "UUID", which is intended to be universally unique. This comes into play for data shared across multiple OpenMRS deployments, such as when a patient's record is transferred into another database, or in the case of common information like the definitions of drugs. Person.getUuid() will return this "UUID". The getUuid() and setUuid() methods are present on most model classes.

Although OpenMRS uses the term "UUID" throughout, be warned that the name is misleading! This identifier is not a UUID in the standard sense (i.e. a 128-bit value with a specific canonical representation as defined in RFC 4122. It is in fact an arbitrary string. Many of the UUIDs you will come across in OpenMRS do look like standard UUIDs in the form "de305d54-75b4-431b-adb2-eb6b9e546014" There are also others that are nothing like UUIDs, such as "5088AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA".