General Overview of config.xml

The module config file config.xml gives vital information about a module to OpenMRS. The config file is parsed and this causes appropriate files to be loaded/cached.

The XML doctype for the config file should be defined as:

<!DOCTYPE module PUBLIC "-//OpenMRS//DTD OpenMRS Config 1.0//EN"
                         "http://resources.openmrs.org/doctype/config-1.5.dtd">

The elements id, name, version, package, author, description, and activator are all required. The remaining elements are optional.

The DTD files are synced daily to http://resources.openmrs.org/doctype/config-x.x.dtd

via our bamboo CI server and build https://ci.openmrs.org/browse/DOC-DOC

Types of XML Elements/Attributes

id: Very important. Should be unique for all modules. Serves as the module's identifier

name: Descriptive name used for display purposes

version: Should be in the form of x.x Used for compatibility comparisons

description: Text describing the module. Used for display

require_version: Text giving the minimum version of the core OpenMRS that is required to run this module. (Example: 1.1.0)
As of v1.6, version can specify an upper bound as well: valid values now: "1.2.", or "1.2.2 - 1.2.3", or "1.2. - 1.3.*", etc. Since config-1.6.dtd multiple version ranges can be specified by using a comma to separate them e.g. "1.8.5 - 1.9, 1.9.8".

require_modules: Allows you to list modules upon which this module depends.

aware_of_modules: Allows you to list modules that this module is aware of but does not require them. Module Dependencies.  Requires config-1.4.dtd and OpenMRS 1.9 and above.

activator: full path to activator. See Module Activator, Must implement org.openmrs.module.Activator Contains startup/shutdown code for the module

updateURL: Http URL to the location of the update.rdf file

mandatory: A value of 'true' here means that if this module doesn't start, OpenMRS should not start. Requires config-1.3.dtd and OpenMRS 1.6. See Mandatory Module.

extension

• Must have child elements 'point', and 'class'.
• See extension points
• point: String referring to the unique extension point labeled the same in the code
• class: Full path to the java class that will be called. Must implement org.openmrs.module.Extension

advice

• Must have child elements 'point', and 'class'.
• See Aspect Oriented Programming (AOP)
• point: String referring to one of the interface of one of the services: i.e. org.openmrs.api.PatientService
• class: Full path to the java class that will be called. Must implement org.aopalliance.aop.Advice or org.springframework.aop.Advisor

privilege

• If the privilege doesn't exist in the OpenMRS system when the module is started, the privilege is added
• Must have child elements 'name, and 'description'.
• name: privilege name. Should be unique across OpenMRS
• description: Text describing the privilege. Added as default description.

setting (formerly globalProperty from platform 1.8 downwards)

• If the setting (formerly global property form platform 1.8 downwards)doesn't exist in the OpenMRS system when the module is started, the property is added
• Must have child elements 'property' and 'description'.
• property: Name of the setting (formerly global property form platform 1.8 downwards)
• description: Text describing the property.
• Optional child elements 'defaultValue', 'viewPrivilege', 'editPrivilege' and 'deletePrivilege'.
• defaultValue: Value of the property if it doesn't exist (defaults to the empty string)
• viewPrivilege: privilege required for a user to view/get this property.
• editPrivilege: privilege required for a user to set/update/save this property.
• deletePrivilege: privilege required for a user to purge this property.

dwr

• Contains dwr code similar to what would be put in dwr.XML
• Should contain an 'allow' and an optional 'signatures' element.

servlet

• Servlets defined by modules are accessed via /openmrs/moduleServlet/moduleId/servlet-name
• Must contain both 'servlet-name' and 'servlet-class' elements
• See Module Servlets
• servlet-name: name/path used for the servlet
• servlet-class: Full path to the java class implementing javax.servlet.http.HttpServlet
• init-param: (Starting from OpenMRS Core 2.7.0)
  • param-name: name of the parameter to pass into the servlet
  • param-value: value of the parameter to pass into the servlet

filter

• Filters defined by modules are executed within the context of the ModuleFilter, which is defined in web.XML. This filter executes for every request, and iterates over every filter defined by each module.
• Configuration follows the same conventions as the Servlet specification - each "filter' element must contain both 'filter-name' and 'filter-class' elements, and supports optional "init-param" elements in order to pass any parameters into the 'filter-class' upon initialization.
• filter-name: unique name to identify the filter
• filter-class: Full path to the java class implementing javax.servlet.Filter
• init-param:
  • param-name: name of the parameter to pass into the filter
  • param-value: value of the parameter to pass into the filter

filter-mapping

• Filter mappings defined by modules are used to determine which Filters should execute for which requests. Configuration of these also follows directly from the Servlet specification.
• filter-name: unique name as defined by a filter element for which this mapping applies
• One of the following url-pattern or servlet-nameelements must then be included:
  • url-pattern: Tries to match the URL pattern specified here against the request URI to determine if this filter should be run for each request. Examples are:
  • / or * - Matches every request
  • .js - Matches every request for a file with a .js extension
  • _/foo/ - Matches every request whose URI starts with _/foo/''
  • servlet-name - Tries to match a servlet that matches the specified servlet-name

messages

• lang: two letter language for the locale
• file: name of the file (i.e. messages.properties or messages_*.properties)
• See ?Module messages.properties Files

NOTE:  Starting from platform 2.0, the messages section is no longer used because message properties files are automatically loaded from the class path. For details regarding this, see TRUNK-4097

mappingFiles

• Whitespace separated list of mapping files to load from the root of the omod.
• Automatically filled in with mavenized modules
• See Module Hibernate Mapping Files

packagesWithMappedClasses

• Whitespace separated list of packages with mapped classes (jpa annotated).
• See Module Hibernate Annotated Classes

conditionalResources

• A list of conditionalResource elements with path, openmrsVersion and modules elements which allow to specify resources to load depending on OpenMRS version and/or running modules.
• All resources are loaded by default. If a path of a conditionalResource is matched based on a regular expression then OpenMRS version and/or modules must match as well for the resource to be loaded.
• modules is a list of module elements with moduleId and version elements.
• Versions are matched with the same algorithm as require_version.
• See Supporting different OpenMRS versions

Config.xml DTD Version History

Changelog

• version 1.1
  • Added version attribute to require_module element.
• version 1.2
  • Added filter, filter-mapping elements to module element.
• version 1.3
  • Added optional mandatory element to module element.

• version 1.4
  • Added aware_of_modules element.
• version 1.5
  • Added packagesWithMappedClasses element
• version 1.6 (awaiting pull request approval) 
  
  • Added conditionalResources element
  • Added openmrsPlatformVersion compatability
  • Supports multiple version ranges for version e.g. "1.8.5 - 1.9, 1.9.8"

OpenMRS Releases & Corresponding Module Configs