This page describes the process of releasing new metadata for the eSaude EMR Platform. All eSaude meta is distributed using the eSaude Metadata Module. Therefore, to publish new metadata, we have to publish a new version of the eSaude Metadata Module(EMM).
The EMM uses the Metadata Sharing Module API(MSM) to install Metadata Sharing(MDS) packages. The packages are creating by hand in a clean instance of the platform, then exported via the admin interface. Exact instructions will be given below.
There are a number of good reasons why metadata should be shared using the EMM. One reason is that it doesn’t require implementers to run scripts against their databases, and therefore eliminates the possibility for them to make mistakes that could result in data loss. Also, using the EMM means that our metadata is versioned in Github, so if necessary, we can always roll back to a previous version.
It is considered best practice in the OpenMRS community for distributions to include their metadata in a module, and the eSaude community should stick to this pattern.
Process
The following process should be followed to add new metadata to the eSaude EMR Platform.
Step 1: Spin Up Clean Platform(Most Probably not Being Used)
For metadata that can be shared using the MSM, we start by spinning up a clean instance of the platform. All new metadata should be created on clean platform Docker containers to remove the possibility of environmental factors influencing the process.
First, if you haven’t cloned the repo, do so as follows:
or if you have, make sure you have the latest changes:
git pull --rebase origin master
Then make sure you have no instances of the platform running natively:
sudo service tomcat7 status
sudo service mysql status
Also make sure no instances are running in Docker:
docker ps
Once you are sure the platform isn’t already running, you can start up a clean instance as follows:
docker-compose -f docker-compose-prebuilt.yml up
This will pull and run the latest prebuilt images. See the README for more details.
❗️If you’re using named volumes, then your new MySQL instance might still be referencing your old data files. Make sure this is not happening and that you are starting with a truly clean database.
Step 2: Create Metadata
Now that you have a clean instance of the platform up and running, you can create the metadata that the MSM supports, such as concepts, forms, encounter types, serialized objects(e.g. SQL cohort queries), etc.
If possible use objects uuids when mapping them, for example when one is referring to an encounter, it would be most accurate to use encounter uuids, use concepts uuids instead of ids since we are NOT guaranteed that MDS will maintain the primary ids when importing data.
📌 You must use the esaude.metadatauser when creating your metadata.
If you need to create metadata that the MSM does not support, see Step 5 below.
Overview
Process
Step 1: Spin Up Clean Platform (Most Probably not Being Used)
git clone https://github.com/esaude/esaude-platform-docker.gitcd esaude-platform-dockergit pull --rebase origin mastersudo service tomcat7 statussudo service mysql statusdocker psdocker-compose -f docker-compose-prebuilt.yml upStep 2: Create Metadata