Adding a CRUD API(*

This document gives all the details about adding new resource to an openmrs module.

For our convenience let us take an example of Surgical Block resource in Operation theater. The resource is available here.

Web API  is usually added in omod folder in  module code. For adding a new resource go to



  • Create new file SurgicalBlockResource which extends DataDelegatingCrudResource => <Name of the domain object>
  • For JVM to identify it as a resource, annotate it with @Resource. We also have to mention the name, supported class (the model/object which we want to load with api call) and openmrs runtime version.
    • Eg: 

      @Resource(name = "/surgicalBlock1", supportedClass = SurgicalBlock.class, supportedOpenmrsVersions = {"2.0.*", "2.1.*"}) 
      public class SurgicalOperationResource extends DataDelegatingCrudResource<SurgicalBlock>
  • In DataDelegatingCrudResource there are some methods which we can override in our class based on the need.
    1. getByUniqueId(String uuid): request get method with uuid
    2. delete(Surgical block, String uuid, RequestContext, requestContext)
    3. save(SurgicalBlock surgicalBlock): create the object
    4. update(String uuid, SimpleObject propertiesToUpdate, RequestContext context) : update the object
    5. getRepresentationDescription(Representation representation): This method will take the representation type and will return DelegatingResourceDescription object. The response can be structured diffrently based on the representation input. There are three representaions: Ref, Default, Full.
if ((representation instanceof DefaultRepresentation) || (representation instanceof RefRepresentation)) {
  DelegatingResourceDescription description = new DelegatingResourceDescription();
  description.addProperty("provider", Representation.DEFAULT);

How to write Integration tests?

Integration tests test from end to end. They create an in-memory database. All the necessary  hbm files need to be added  <module>/omod/src/test/resources/test-hibernate.cfg.xml.

In hibernate-configuration section like below

<mapping resource="BedPatientAssignment.hbm.xml"/>
<mapping resource="Bed.hbm.xml"/>

At run time the hibernate configurations are picked up from here <module>/omod/src/test/resources/TestingApplicationContext.xml.

<property name="configLocations">

........ work in progress...