This project is still at the experimental stage though is being actively used within the KenyaEMR distribution

This Maven plugin provides support for OpenMRS based distributions. Such distributions typically bundle a lot of content (metadata, concepts, forms, reports) with their code and this plugin seeks to help developers more easily manage that content.

Source codehttps://github.com/I-TECH/openmrs-contrib-maven-plugin-distrotools
DevelopersUnknown User (rowanseymour)

Background

A common challenge for distributions (or any module that bundles metadata) is referencing metadata objects, of which a large distribution will have many. The OpenMRS API provides several options which have their own strengths and weaknesses:

There also may be several places in the distribution where references to database objects exist. For example one might reference metadata objects in:

For a large distribution it can be difficult to keep all those references in consistent and there is no way of knowing at build time whether references are correct, e.g. you don't know if a reference term used in an HTML form is correct until you open that form on a real system.

Solution

This project seeks to provide a new unified way of referencing metadata. The general principles are:

The implementation borrows ideas from the Android SDK which generates some Java sources based on resource descriptions in XML files. It leverages Maven's resource filtering system to resolve metadata references in non-Java files.

The input metadata reference lists have a simple format and should be placed in api/src/main/distro/metadata. For example the contents of a simple concepts.xml might look like:

<refs type="Concept">
  <ref key="YES" uuid="1065AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" />
  <ref key="NO" uuid="1066AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" />
</refs>

From that we generate a Java source file of constants, e.g.

public class Metadata {
  public static class Concept {
    public static final String YES = "1065AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA";
    public static final String NO = "1066AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA";
  }
  ...
}

Which can be used now in the distribution code to reference the concepts as Metadata.Concept.YES and Metadata.Concept.NO. We also generate a properties file to be used for resource filtering, e.g.

metadata.concept.YES=1065AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
metadata.concept.NO=1066AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
...

Which means distribution resource files can reference the concepts as ${metadata.concept.YES} and ${metadata.concept.NO}. At build time those will be replaced with the corresponding concept UUIDs. For example if you are using the UI Framework to localize metadata names then your messages.properties file can now include something like:

ui.i18n.Concept.name.${metadata.concept.YES}=Yes
ui.i18n.Concept.name.${metadata.concept.NO}=No
...

Current Limitations

Plugin Usage

Firstly, add the plugin to your module's main pom.xml:

<pluginManagement>
  <plugins>
    <plugin>
      <groupId>org.openmrs.maven.plugins</groupId>
      <artifactId>distrotools-maven-plugin</artifactId>
      <version>0.5</version>
    </plugin>
  </plugins>
</pluginManagement>

Goal Configuration

generate-metadata-sources

Generates metadata reference source files from input XML files (for now this is just concepts and forms). This includes two files:

Configuration:


<build>
  <plugins>
    <plugin>
      <groupId>org.openmrs.maven.plugins</groupId>
      <artifactId>distrotools-maven-plugin</artifactId>
      <executions>
        <execution>
          <phase>generate-sources</phase>
          <goals>
            <goal>generate-metadata-sources</goal>
          </goals>
          <configuration>
            <outputPackage>${project.parent.groupId}.${project.parent.artifactId}</outputPackage>
          </configuration>
        </execution>
      </executions>
    </plugin>
    <plugin>
      <groupId>org.codehaus.mojo</groupId>
      <artifactId>build-helper-maven-plugin</artifactId>
      <version>1.8</version>
      <executions>
        <execution>
          <id>add-source</id>
          <phase>generate-sources</phase>
          <goals>
            <goal>add-source</goal>
          </goals>
          <configuration>
            <sources>
              <source>${project.build.directory}/generated-sources/distro</source>
            </sources>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
  ...
  <filters>
    <filter>${project.build.directory}/metadata.properties</filter>
  </filters>
  ...
</build>

validate-forms

Performs basic validation (DOM validation, macro application) all HFE form files in a specified directory.

Configuration:


<plugin>
  <groupId>org.openmrs.maven.plugins</groupId>
  <artifactId>distrotools-maven-plugin</artifactId>
  <executions>
    <execution>
      <phase>validate</phase>
      <goals>
        <goal>validate-forms</goal>
      </goals>
      <configuration>
        <formsDirectory>src/main/webapp/resources/htmlforms</formsDirectory>
      </configuration>
    </execution>
  </executions>
</plugin>