Skip to content
Metadata and configuration for PIH's HUM implementation
Java Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Managing Metadata for a PIH EMR instance of OpenMRS

Metadata is packaged for deployment across PIH EMR instances using two OpenMRS modules: Metadata Sharing and Metadata Deploy. Please read the documentation in the links.

Metadata Server Management

This is described on the OpenMRS wiki.

MDS Package Search Tool

You will at some point want to look up whether a concept exists in some or another package. To accomplish this you can use the tool in mds-search. cd into mds-search. Then run ./ to unzip all the MDS packages in this repo into the mds-search directory. Then use ./ 123 to find the bundles that contain the concept with PIH concept ID 123.

PIH EMR Concept Management Process

  1. Write down your required question/answer/diagnosis in a row in your requirements sheet.
  2. Try and find a suitable concept in the PIH Concept dictionary.
    1. If there is a suitable concept, then add its ID to your requirements sheet
    2. If there's no suitable concept, then search for a suitable concept in CIEL on OCL.
      1. If there is a suitable concept in CIEL, add the CIEL ID to your requirements sheet and ask Ellen to import the concept from CIEL to PIH.
      2. If there is no suitable concept in CIEL, then ask Ellen what the best next step is. It will be either to
        1. Propose a new concept for CIEL via an email to Andy (Andrew Kanter), and wait for it to be created and for Ellen to import it from CIEL to PIH. Once this is done, add the CIEL Concept ID to your requirements sheet. This will be the right choice when the concept seems like something that lots of other organizations would want.
        2. Just create a new concept in the PIH Concept dictionary, then add the PIH ID to your requirements sheet. This will be the right choice for things that are very specific to your implementation.
  3. Once you have the concept in the PIH concept server, make sure it has a reference term mapping. The ones imported from CIEL should certainly have the CIEL code as a mapping -- if it isn't present, definitely ask Ellen about it. Concepts which don't correspond to anything in CIEL should have PIH reference term mappings, for the ID (e.g. "PIH:12345") and for the name (e.g. "PIH:HAS BOO BOO"). The ID one probably isn't important, actually, but it'll probably exist.
  4. Check that a translation of the concept name exists in your implementation’s language. If it doesn't, evaluate whether or not the display name you want for the concept is a direct translation of the English concept name.
    1. If it is, add the display name as the translation for the concept.
    2. If it isn't, translate the English concept name as best you (or a bilingual colleague) can. You'll add the display name to the file later.
  5. Use the MDS Package Search Tool (mds-search), documented above, to find out whether the concept you want is already in an MDS package.
  6. If the concept is new or is for some other reason is not yet in an MDS package, you or someone from MedInfo will have to add it to one.
    1. Identify the MDS package it should go in. Ask someone if you're not sure.
    2. Add your concept to a concept set that goes into that package. Ask someone if you're not sure.
    3. Go to Administration > Export Metadata.
    4. Click on "New Version"
    5. I don't think we use publication, but feel free to check "2. Publish package" anyway. Click "Next."
    6. If you have a new concept set that's not yet in the package, then
      1. Under "4. Review selected items," click "Choose Individually."
      2. Find and select the concept set you'd like to include.
      3. Click "Save."
    7. Click "Export."
    8. Download this newly created MDS package.
    9. Open the "openmrs-module-mirebalaismetadata" repository on your computer. If you don't have it, check it out from GitHub. If you are using the OpenMRS SDK, be sure to watch it with openmrs-sdk:watch.
    10. Drop the new version of the MDS package into api/src/main/resources.
    11. Update the filename in api/src/main/resources/packages.xml to reflect the new version number.
  7. To make sure that your site is importing that MDS package, look at mirebalaismetadata/.../ It should have a list of MDS packages under your country's name. Make sure your MDS package is named there, adding it if necessary.
  8. Now that you know that the concept is being imported via an MDS package, you can use it in a form (or whatever). Refer to your concept by Reference Term Mapping. If a CIEL Metadata Term Mapping ("CIEL:3456") is available, always prefer that. If it's not obvious from context what the concept is, add a comment with the concept's name. If the concept is not a CIEL concept, use the PIH name mapping ("PIH:TUMMY ACHE"), creating it if necessary.
  9. Add the display name to the correct file, with the correct key (I haven't done this yet and can't be more helpful than that).

Importing Concepts from CIEL to PIH Server

  1. Use Metadata Sharing (mds) to add the concept to the PIH EMR package.

    1. Create mds package with select CIEL concepts.

    2. Download/Export the CIEL mds package.

    3. Import the CIEL mds package into the PIH concepts server.

    4. Add the concepts to one of the PIH EMR mds packages. Zip file updates are pushed to the repo

Metadata Sharing (mds)

Currently used for concepts.

New concepts are created using the Concept Dictionary Maintenance UI:** (NOTE: Do not add/edit concepts without first consulting Ellen Ball)**

Concepts are bundled into zip files using the Metadata Sharing module in the admin UI.

Zip file updates are pushed to the repo

The metadata module is built daily using Bamboo and deployed to all configured servers.


This commit adds the concept "Name of community health worker":

Open to view the concept XML file. As a reference, the concept can also be viewed in the administrative UI:

Metadata Deploy

Used for code level configuration of ALL other metadata. Metadata is set up programmatically in pih-core via methods provided by the metadata deploy module.


Location and Patient Identifier Type for Mexico:

Other common metadata:

Configuring Concepts for Chiapas

  1. On the concepts server (, create a "Mexico MoH (Ministry of Health, or equivalent..) concept set", similar to the “Liberia MoH diagnosis set”. Create child sets, e.g. “Mexico MoH diagnosis”, “Mexico MoH Labs”, etc. Add concepts to these subsets.

  2. For each concept in the source data dictionary:

    1. If there is an existing concept in the concepts server that is an exact match, add a mapping to the "Mexico MoH" vocabulary item, and a Spanish translation if required.

    2. If there is no existing concept, create it and add vocabulary mapping and translation.

    3. Add this concept to appropriate concept set.

  3. In the Metadata Sharing module, create a package called "Mexico Concepts" and create a new version. See example here for “Liberia Concepts”.

  4. Download the zipped package of this version.

  5. Add the zip file to the PIH openmrs-module-mirebalais-metadata Github repo here. This will add the metadata concepts to our build pipeline.

  6. The concepts should then be available companero staging server.


Add diagnoses concept set setting here:


You can’t perform that action at this time.