Wiki Spaces


Get Help from Others

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


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

Let's start with a short comparison of 1.x and 2.x:

  1. 2.x supports OpenMRS 1.9 without installing the 1.9 extension module, which was needed when using 1.x.
  2. 2.x exposes the same resources as 1.x and preserves the JSON format, but adds a better support for Concept mappings.
  3. 2.x has a single controller, which serves all resources. You do not have to create controllers for your custom resources as it was in 1.x.
  4. The 2.x @Resource annotation includes name, supportedClass, supportedOpenmrsVersions and order in comparison to 1.x which only had value (name).
  5. The 2.x @SubResource annotation includes parent, path, supportedClass, supportedOpenmrsVersions and order in comparison to 1.x which only had parent and path.
  6. 2.x reorganizes java packaging of resource classes and class names to include a corresponding version of OpenMRS i.e. 1_8 or 1_9.
  7. 2.x introduces new SearchHandlers, which allow you to implement custom searches for any resource.
  8. 2.x tests resources by accessing actual URLs instead of controller methods.
  9. 2.x is now officially supported version of the module. We will not add new features or fix bugs in 1.x.

If you didn't implement any custom resources or subresources and you were just a consumer of JSON, the migration will not require from you any work other than uninstalling 1.x and installing 2.x. We have not changed any resources aside from Concept, which only received one new property for mappings. We also corrected a path for the location resource in OpenMRS 1.9, which was wrongly exposed at /rest/ws/v2/location instead of /rest/ws/v1/location.

If you did implement custom resources in your own module, then you will have to adjust to new packaging, resource/subresource annotations and remove resource controllers. It is pretty straightforward, yet it can be tedious depending on how many custom resources you have.

Let's consider a specific example. We want to move ObsResource to 2.x. You need to start from changing dependencies in your poms and creating a single controller to define your module namespace. See Adding a Web Service Step by Step Guide for Core Developers.

  1. Open and remove @Handler. Change the resource annotation to @Resource(name = "obs", supportedClass = Obs.class, supportedOpenmrsVersions = { "1.8.", "1.9." }). Fix imports if any.
  2. Open You can see that it has two custom search methods. Create ObsSearchHandler implementing SearchHandler, which can do the same searches depending on which request parameter is given. The alternative is to implement searches directly in the resource by overriding the doSearch method. We recommend SearchHandler as it is more robust.
  3. Remove It is no longer necessary since all requests are handled by the main controller and you moved custom searches to ObsSearchHandler.
  4. If you had which called ObsController methods, then you need to change it to extend MainResourceControllerTest and call newGetRequest, newPostRequest or newDeleteRequest with the correct URL. See the new for example.

That's it! Let us know if you have any questions.

  • No labels