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


This tool has been replaced by the OpenMRS SDK. Use that instead.

Setup of module wizard

Prerequisite: Maven should be installed in you system. Check the command "mvn --version". It should display your system and maven properties.

Copy the below OpenMRS profile tag into your Maven settings.xml. The file may be found (depending on your OS) in:

  • Linux: ~/.m2
  • Windows: C:\Documents and Settings\$USER$\.m2
  • Vista/Windows7: C:\Users\$USER$\.m2

If you prefer not to modify your user Maven settings, you can point to temporal settings by specifying the -s parameter

mvn -s path_to_settings.xml [other options] [<goal(s)>] [<phase(s)>]

If the settings.xml file does not exist, create the file and copy into it the following:

<settings xmlns=""

          <name>OpenMRS Nexus Repository</name>
          <name>OpenMRS Nexus Repository</name>


Using module wizard

  1. Go to a folder where you want to create a project (like your workspace folder)
  2. Run the following maven plugin command

    mvn module-wizard:generate


    mvn module-wizard:generate -s path_to_settings.xml
  3. Follow the wizard questions

The wizard prompts with the following pattern:
question: default answer: : <input by user>

For instance "groupId: org.openmrs.module: : <input by user>" is a question about "groupId" with a default answer "org.openmrs.module".
The default answer will be set if you do not type anything and press enter.

If a question ends with "(y/n)" then an answer should be a letter 'y' (yes) or 'n' (no) (case insensitive).
For instance "Do you want to add an admin page link (y/n): n: : <input by user>" requires to answer 'y' or 'n' with a default answer 'n'.

Valid OpenMRS versions to depend on can be found in our maven repository

Example output




File Structure


Creation of basic Demo Module:     

  • It creates basic file structure of an openmrs module with a     
  • To create a basic module you should set all other module wizard questions to 'n'.


Creation of Demo Module with a link in the admin page:     

  • It creates a module similar to basic module with extra file to create a link in the OpenMRS admin page under the module name as well as a controller and a jsp page for that link.
  • To create a module with an admin link you need to answer "y" (default) to module wizard question "Do you want to add an admin page link (y/n)".


Creation of Demo Module with a service/dao layers:

  • Creates a module with a Service, ServiceImpl, DAO, HibernateDAO, POJO, Hibernate mapping, liquibase.xml and sqldiff.xml.
  • To create a module with service/dao files you need to answer "y" (default) to module wizard question "Do you want to add a service layer" and specify service and pojo names

Headless install (no prompts) 

User can directly create modules skipping the prompts by making the interactive mode parameter false.

mvn module-wizard:generate -DinteractiveMode=false

To change a default-value of a parameter, pass the parameter expression concatenating with -D with a value.

mvn module-wizard:generate -D<parameterExpression>=<value>

Parameter Description


Default Value

Group Id



Artifact Id




(set internally)





Module name


Basic Example

Module name with no spaces

(set internally)


Module description


Helps to start writing OpenMRS modules

Module author


OpenMRS version to depended on



Do you want to add an admin page link (y/n)



Do you want to add a service layer (y/n)



Service name



Object name



Do you want to add another module to depend on (y/n)




  • The module name is appended with " Module" .
    Module name = moduleName + " Module"
  • Dependent modules should be passed as a comma-separated list of moduleID:version i.e.:
    <Module 1 Id>:<Module 1 Version>,<Module 2 Id>:<Module 2 Version>,...



Creating a Demo module with a link in admin page and a dependent module with out any prompts.

mvn module-wizard:generate -DinteractiveMode=false -DartifactId=demo -DmoduleName=Demo -DmoduleDescription="A demo module" -DopenmrsVerison=1.8.0 -DdependentModules=cohort:1.0.2

Importing module to your IDE

In Eclipse, import the created module by selecting File -> Import -> Existing Maven Projects. You will observe a parent project (name=artifactId) and two child projects, api (name=artifactId-api) and omod (name=artifactId-omod).

  • No labels


  1. I was experiencing the problem that every time I would create a module with the archetype, its module dependencies would not be marked with scope=provided.

    Apparently this was caused by an old version of the archetype, because I had incorrect values in my settings.xml:

    <!-- THIS IS WRONG -->

    and I had no archetypeRepository entry.

    This must have come from following an old version of instructions on how to use the archetype. So, if you're having trouble using the latest version of the archetype, make sure that your settings.xml has the configuration currently shown on this page.

  2. For people who are behind a proxy as was in my case.... also add some more lines in settings.xml...

    follow this link: ""


  3. There is a known bug in Maven (see when a maven project contains sub-projects that depend on each other.   It causes maven to fail when doing mvn compile (and probably some other maven goals).  But mvn package or mvn install should work.

    The error I saw when doing mvn compile looked like the following:

    [ERROR] Failed to execute goal org.apache.maven.plugins:maven-dependency-plugin:2.1:unpack-dependencies (Expand resources) on project Unknown archiver type: No such archiver: 'rest/omod-common/target/classes'.

  4. If you are using windows, the maven settings.xml which can be edited to add the OpenMRS profile tag can be found under the conf folder of the maven directory (Use the command "mvn --version" to view your maven directory).

    Adding the settings.xml into the .m2 directory sometimes will not work and that means the maven command "mvn module-wizard:generate" will fail.