Module Servlets

Modules can add any number of http servlets to OpenMRS. Servlets only need to be named unique to the module because all module servlets are accessed via urls like http://.../openmrs/moduleServlet/formEntry/servletName.

Each servlet must be defined in the config.xml file:


The tag definition is far simpler than the similar definition used in a web.xml file. The servlet-namecannot contain a wildcard character. The name can either be the final string in the url, or just the first of many in the url. For example, for the previous definition, the url http://.../openmrs/moduleServlet/formEntry/formsANDhttp://.../openmrs/moduleServlet/formEntry/forms/15.xsn would be directed to theorg.openmrs.module.formEntry.web.XsnDownloadServletclass.

The servlet-class is expected to extend the javax.servlet.http.HttpServlet class.

intialize()/destroy() methods are called at your module's startup and shutdown. (as of OpenMRS v1.5)

As of OpenMRS 1.5 you can also use a shortened url: "http://.../openmrs/ms/formentry/forms/15.xsn" or even just the servlet name: "http://.../openmrs/forms/15.xsn".


Good Module Design/Layout

In the module structure, Servlets should be placed in the /web/src/... folder.

The Servlet should at least implement both the doGet(HttpServletRequest, HttpServletResponse) and doPost(HttpServletRequest, HttpServletResponse).



Module servlets do not implement the full servlet specification.

  • Wildcard urls are not allowed either. A "*" is assumed in the "servlet-name": a servlet mapped with a name of "forms" would be called with urls: "form", "forms", "form/asdf", etc
  • Module servlets don't have access to a ServletContext. Calls to getServletContext() will throw.
  • Init parameters are not supported for module servlets


Starting with Platform 2.0.0, you may dynamically define a (real) servlet that does not have the limitations of OpenMRS Module Servlets. See an example of this in the Legacy UI module.

The limitation of this alternative approach is that it will fail if you add, remove, or upgrade any installed modules without restarting the entire OpenMRS web application.