Wiki Spaces


Get Help from Others

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


Skip to end of metadata
Go to start of metadata

Naming Your Module

  • Module id should be all lowercase without spaces. We prefer no breaks in the word (e.g., htmlformentry); however, you may use hyphens if absolutely necessary.
    • The Module id should correspond with the unqualified top-level package for classes in the module. So, would have an id of foo.
    • Avoid using a module id that conflicts with existing modules or tables that already exist in the data model — e.g., "concept" and "form" would be undesirable module ids, since there are existing tables with these names.
    • Implementations of special functions should use dot notation: serialization.xstream, webservices.jaxws. (and this means a package of org.openmrs.module.serialization.xstream)
  • Module name should be concise (ideally less than 20-25 letters), may contain spaces and upper case characters, but should avoid punctuation. It does not have to match the module id exactly.

Project Layout

If your module is on Git Hub, see the the Git conventions here

Module developers are encouraged to follow Subversion's suggested directory layout if your module is in SVN:


README conventions for modules in SVN

Each module should contain a README file within the trunk folder (or root folder if not using the trunk/branches/tags folder convention in subversion).  The README may be named README, README.txt,, or README.markdown (use .md or .markdown extension for a README using markdown syntax).

Your README should contain at least two sections: description and installation.  For example:

== Description ==

This should be the description of your module.  Write your description in a way that will help 
someone who knows nothing about your module or your projects to understand the purpose of your 
module and what feature(s) it provides.  If there are additional resources/documentation that 
describe your moule, then direct the reader to those resources in your description.

== Building from Source ==

You will need to have Java 1.6+ and Maven 2.x+ installed.  Use the command 'mvn package' to 
compile and package the module.  The .omod file will be in the omod/target folder.

== Installation ==

1. Build the module to produce the .omod file.
2. Use the OpenMRS Administration > Manage Modules screen to upload and install the .omod file.

Module Tables

  • Module table names should begin with the module id — e.g., all tables added for a the "formentry" module should have table names beginning with "formentry_*".
  • Be careful when naming your module to avoid conflicts with other modules or existing tables

Module Project Management

  • While module developers are welcome to use their own ticketing system, we encourage module developers to use ?JIRA to track bugs and enhancement requests.
  • Request a new JIRA project for your module by opening a ticket.
  • Add milestones for your module to the Technical Road Map using the naming convention: <module name> Module x.x — e.g., FormEntry Module 1.0. Make one milestone for the current version and one for the next version. Optionally, you can make a milestone entitled "<module name> Module Someday" for enhancements not anticipated in the next version.
  • Module authors are responsible for keeping tickets and milestones for their module up to date

UI Conventions

  • Module admin pages should fit in with other admin pages. Users like a standard look. Fancy js windows are cool but they have their place. Mimic the core jsp pages


  • Don't include a log4j.xml: this will override the configuration in core and possibly break it. It also prevents system administrators from managing logging. If you need to change the log4j configuration then use the LogManager module. In a Mavenized module you can however include a log4j configuration file just for testing by placing it in src/test/resources.
  • Use per class loggers: put the following line at the top of each class in your module:
  • Logging exceptions: if you have a throwable (e.g. ex), use the pattern: log.debug("Concise title for debug message", e). Do not use the anti-pattern of: _log.debug(e) as there is no log.debug(Throwable) method, so the exception is cast to a string and the stack trace is lost.
  • Expensive log messages: If you're going to log a message that is computationally intensive to calculate, use the isDebugEnabled, isWarnEnabled, isErrorEnabled methods. For example:

See Also

  • No labels