The goal of the module system is to allow other developers to write and integrate code into OpenMRS without having to modify the core code base. Our online Add-ons index has been developed to facilitate searching and sharing of modules.

What's in a Module omod?

An omod is simply a renamed jar file.  And a jar file is simply a special zip file.  OpenMRS expects the file to contain a config.xml file in the root.  The root lib folder should contain new/unique jars that the module is providing to the system.  All messages.properties files should also be in the root folder.

Getting Started

See the Module Conventions page for existing conventions for naming your module, coming up with a module ID, creating module-specific tables, etc.

For a step-by-step walkthrough, see Creating Your First Module

If you don't feel like reading that, checkout the basicmodule at http://github.com/OpenMRS/openmrs-module-basicmodule.git following the steps described here

You can find and check out a lot of examples from Git Hub at http://github.com/OpenMRS. See projects starting with "openmrs-module-example". Following the steps described here to check out the code

For a more detailed introduction, download the EHSDI Training Course.  Module development is covered in lectures 8 and 9 of course EH204 OpenMRS Development. 

Module File Structure

If viewed as a single mavenmodule project:

Building Your Module

Assuming your module is using Maven (with the layout above), you can build at the command line using mvn package or from within Eclipse by right clicking on the project root, and choosing Run As --> Maven Package

You can find the packaged omod in the /omod/target folder.

Installing Your Module

In a running OpenMRS you can use the Manage Modules page linked to from the Administration page. 

If uploads are not allowed from the web (changable via a runtime property), you can drop the omod into the ~/.OpenMRS/modules folder.  (Where ~/.OpenMRS is assumed to be the Application Data Directory that the running openmrs is currently using.)  After putting the file in there simply restart OpenMRS/tomcat and the module will be loaded and started.

Tips While Developing Your Module

It is a tedious task to build and install the module each time you change something and you want to test it. In order to make the process slightly more efficient you can add the following snippet to your omod/pom.xml:

<profiles>
  <profile>
    <id>deploy-web</id>
    <build>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-antrun-plugin</artifactId>
          <executions>
            <execution>
              <phase>package</phase>
              <goals>
                <goal>run</goal>
              </goals>
              <configuration>
                <tasks>
                  <copy todir="${deploy.path}/WEB-INF/view/module/${project.parent.artifactId}">
                    <fileset dir="src/main/webapp" includes="**/*" />
                  </copy>
                </tasks>
              </configuration>
            </execution>
          </executions>
        </plugin>
      </plugins>
    </build>
  </profile>
</profiles>

It will allow you to deploy any changes to your web resources such as jsp or js files without re-installing the module. You only need to select the deploy-web profile and specify the deploy.path variable. The deploy path says where OpenMRS is deployed. It should point to an openmrs directory in Tomcat or to a directory where jetty looks for file changes. The path can be relative (to the omod directory) or absolute. You can do it in your IDE or from the command line as follows:

mvn package -P deploy-web -D deploy.path="../../openmrs-1.8.x/webapp/src/main/webapp"

It is executed with the package phase thus works for package and higher goals like install. 

Other Resources

Publishing your Module

The Add-ons index is available to everyone. Read more about the module release process here. Also read more about our rules and regulations for it here: Module Repository .

FAQ