{"type":"doc","content":[{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"This project is still at the experimental stage though is being actively used within the ","type":"text"},{"text":"KenyaEMR","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/docs/pages/25475417"}}]},{"text":" distribution","type":"text"}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"table","content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Source code","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"https://github.com/I-TECH/openmrs-contrib-maven-plugin-distrotools","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/I-TECH/openmrs-contrib-maven-plugin-distrotools"}}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Developers","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"type":"mention","attrs":{"id":"712020:1317414b-83b5-4acb-95f8-6bebce5e53c4","text":"@Rowan Seymour"}}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Background","type":"text"}]},{"type":"paragraph","content":[{"text":"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:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Database id","type":"text","marks":[{"type":"strong"}]},{"text":" (all metadata classes)","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Pros: succinct...","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Cons: not portable between different databases","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Name","type":"text","marks":[{"type":"strong"}]},{"text":" (some metadata classes can be fetched by name, e.g. ","type":"text"},{"text":"EncounterType","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"Program","type":"text","marks":[{"type":"code"}]},{"text":" etc)","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Pros: human readable","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Cons: the primary purpose of name is for display in the UI layer so it might be changed","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"UUID","type":"text","marks":[{"type":"strong"}]},{"text":" (all metadata classes)","type":"text"},{"type":"hardBreak"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Pros: guaranteed to be globally unique and unchanging","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Cons: not human readable","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Reference term","type":"text","marks":[{"type":"strong"}]},{"text":" (so far just ","type":"text"},{"text":"Concept","type":"text","marks":[{"type":"code"}]},{"text":" but soon also ","type":"text"},{"text":"Drug","type":"text","marks":[{"type":"code"}]},{"text":")","type":"text"},{"type":"hardBreak"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Pros: can be human readable if descriptive text is used (debatable whether this is a good practice)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Cons: not guaranteed unique and small performance hit due to extra database table joins","type":"text"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"There also may be several places in the distribution where references to database objects exist. For example one might reference metadata objects in:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Configuration resources (e.g. application context, JSON files)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Java code (e.g. a constants class)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Liquibase changeset files","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"HTML form content (whether in resource files or database)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Localization files (e.g. messages.properties used in conjunction with UIFR metadata localization)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"XML dataset files for testing","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Solution","type":"text"}]},{"type":"paragraph","content":[{"text":"This project seeks to provide a new unified way of referencing metadata. The general principles are:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"There should be ","type":"text"},{"text":"one","type":"text","marks":[{"type":"em"}]},{"text":" central place for metadata references which is accessible throughout the distribution","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"There should be more validation of metadata references at build time","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The implementation borrows ideas from the ","type":"text"},{"text":"Android SDK","type":"text","marks":[{"type":"link","attrs":{"href":"https://developer.android.com/sdk/"}}]},{"text":" 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.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":39.0},"content":[{"type":"media","attrs":{"width":1280,"id":"9c8db942-e5b8-47df-b7eb-02c5c8f0aaaf","collection":"contentId-27009224","type":"file","height":777}}]},{"type":"paragraph","content":[{"text":"The input metadata reference lists have a simple format and should be placed in ","type":"text"},{"text":"api/src/main/distro/metadata","type":"text","marks":[{"type":"em"}]},{"text":". For example the contents of a simple concepts.xml might look like:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Example concepts.xml","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n \n \n","type":"text"}]},{"type":"paragraph","content":[{"text":"From that we generate a Java source file of constants, e.g.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Example generated constants file","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"java"},"content":[{"text":"public class Metadata {\n public static class Concept {\n public static final String YES = \"1065AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\";\n public static final String NO = \"1066AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\";\n }\n ...\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Which can be used now in the distribution code to reference the concepts as ","type":"text"},{"text":"Metadata.Concept.YES","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"Metadata.Concept.NO","type":"text","marks":[{"type":"code"}]},{"text":". We also generate a properties file to be used for resource filtering, e.g.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Example generated properties file","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","content":[{"text":"metadata.concept.YES=1065AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\nmetadata.concept.NO=1066AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\n...","type":"text"}]},{"type":"paragraph","content":[{"text":"Which means distribution resource files can reference the concepts as ","type":"text"},{"text":"${metadata.concept.YES}","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"${metadata.concept.NO}","type":"text","marks":[{"type":"code"}]},{"text":". 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 ","type":"text"},{"text":"messages.properties","type":"text","marks":[{"type":"em"}]},{"text":" file can now include something like:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Example messages file containing metadata references","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","content":[{"text":"ui.i18n.Concept.name.${metadata.concept.YES}=Yes\nui.i18n.Concept.name.${metadata.concept.NO}=No\n...","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Current Limitations","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Keeping the metadata reference lists in the module API makes it harder to re-use them in the module OMOD project.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Won't work with webapp resources that are being dynamically reloaded in UI Framework's development mode (e.g. HTML form resources)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"No automated way to generate testing datasets (this will hopefully be implemented as part of ","type":"text"},{"text":"this GSoC project","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/projects/pages/27009216"}}]},{"text":").","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Plugin Usage","type":"text"}]},{"type":"paragraph","content":[{"text":"Firstly, add the plugin to your module's main pom.xml:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Plugin dependency in main pom.xml","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n \n \n org.openmrs.maven.plugins\n distrotools-maven-plugin\n 0.5\n \n \n","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Goal Configuration","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"generate-metadata-sources","type":"text"}]},{"type":"paragraph","content":[{"text":"Generates metadata reference source files from input XML files (for now this is just concepts and forms). This includes two files:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A Java source file of constants (","type":"text"},{"text":"Metadata.java","type":"text","marks":[{"type":"code"}]},{"text":")","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A properties file for filtering of resources containing metadata references (","type":"text"},{"text":"metadata.properties","type":"text","marks":[{"type":"code"}]},{"text":")","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Configuration:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"metadataDirectory","type":"text","marks":[{"type":"em"}]},{"text":" the directory containing the XML files","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Required: no","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Type: File","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Default: ","type":"text"},{"text":"src/main/distro/metadata","type":"text","marks":[{"type":"em"}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"outputDirectory","type":"text","marks":[{"type":"em"}]},{"text":" the output directory for generated source files","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Required: no","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Type: File","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Default: ","type":"text"},{"text":"target/generated-sources/distro","type":"text","marks":[{"type":"em"}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"outputPackage","type":"text","marks":[{"type":"em"}]},{"text":" the output package for generated source files","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Required: yes","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Type: String","type":"text"}]}]}]}]}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Example configuration of generate-metadata-sources in api/pom.xml","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","content":[{"text":"\n \n \n org.openmrs.maven.plugins\n distrotools-maven-plugin\n \n \n generate-sources\n \n generate-metadata-sources\n \n \n ${project.parent.groupId}.${project.parent.artifactId}\n \n \n \n \n \n org.codehaus.mojo\n build-helper-maven-plugin\n 1.8\n \n \n add-source\n generate-sources\n \n add-source\n \n \n \n ${project.build.directory}/generated-sources/distro\n \n \n \n \n \n \n ...\n \n ${project.build.directory}/metadata.properties\n \n ...\n","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"validate-forms","type":"text"}]},{"type":"paragraph","content":[{"text":"Performs basic validation (DOM validation, macro application) all HFE form files in a specified directory.","type":"text"}]},{"type":"paragraph","content":[{"text":"Configuration:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"formsDirectory","type":"text","marks":[{"type":"em"}]},{"text":" the directory containing the form files","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Required: yes","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Type: File","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"formsExtension","type":"text","marks":[{"type":"em"}]},{"text":" the file extension used for form files","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Required: no","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Type: String","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Default: html","type":"text"}]}]}]}]}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Example configuration of validate-forms in omod/pom.xml","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n org.openmrs.maven.plugins\n distrotools-maven-plugin\n \n \n validate\n \n validate-forms\n \n \n src/main/webapp/resources/htmlforms\n \n \n \n","type":"text"}]}],"version":1}

Browser not supported