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.


The API allows developers to interact with the complex OpenMRS ? Data Model with common Java objects.  This provides greater data integrity as well as a simple to use approach.

Also see:See

Java Objects vs Tables

Most of the tables in the data model have a one-to-one relationship with a Java object in the OpenMRS API.

Compare the person patient table (in the data model) with the person java object :

  • There is a "gender" column and "getGender/setGender" methods.


  • A "birthdate" column and "get/setBirthdate" methods.


  • The "person_name" table contains any number of names of a person.


  • You can find a list of PersonName objects on the Person object.

Persisting and Retrieving Objects

To get data into and out of the database you go through the objects and services.   If you want a person with id #1, you ask the PersonService for the Person object:


The Services in the OpenMRS API make sure that only the correct columns are saved/updated in the database.

The Context Singleton

All services are accessed in a static way from the org.openmrs.api.context.Context object.   You do not have to instantiate a new "Context" object and you do not ever call "new" on a service.

The primary usage of the Context is to get the services so you can fetch and persist things in the database:

Code Block
UserService userService = Context.getUserService();
UserList<User> bobObjectbobObjects = userService.findUsergetUsers("bob");

The Context object has two primarily goals. Access to the OpenMRS services and access to other usage is to access the currently logged in user .The currently logged in userand their locale settings:

Code Block
User u = Context.getAuthenticatedUser();


Code Block
Locale loc = Context.getLocale();

The currently logged in user's date pattern layout:

Code Block

String dataPatternString = Context.getDatePattern;

Programming to Interfaces


In order to create a new implementation of a service (for whatever unknown reason that would be in the future), we would only need to change the file specified in Spring's /api/src/main/resources/applicationContext-services.xml file.

Authentication and Authorization

Users are authenticated against the ContexContext.

Code Block
Context.authenticate("bob", "password");


Within the webapp, a session is determined by Spring's OpenSessionInViewFilter. Every request is wrapped with an open session and close session. This is identical to how we were operating under the old api. The only difference now is that that session is now one single transaction., see the OpenmrsFilter class.

Outside the webapp , a session should be wrapped with calls to Context.openSession() and Context.closeSession(). See How To Use the OpenMRS API

To wrap a service within a transaction we use annotations on the interface: