Main Page

Configuration

Go to Administration → Metadata Sharing → Configure

Concept Source

Any time that you share a Concept using the Metadata Sharing module, it will be tagged with its internal conceptId from your database. This allows people to share Concepts without central coordination, while still allowing them to know if the same concept already exists in their database.

To do this, your database needs a Concept Source to represent the internal ids of concepts in your database. This Concept Source must be unique to your server. If you do not have a suitable Concept Source, you need to create one in order to be able to export Concepts.

The module guarantees that all Concepts you export have at least one mapping in a format "CONCEPT_SOURCE:INTERNAL_ID". If such a mapping does not exist, it will be automatically added upon export. It is allowed for a Concept to have two and more mappings which refer to the same Concept Source.

Mappings are maintained by the Metadata Sharing module, however, they are not used internally by the module at the moment. In the future they will be used to find similar Concepts.

Mappings are never deleted from your Concepts regardless if you choose to overwrite or replace. This approach allows to track the origin and evolution of Concepts.

URL prefix

The URL prefix is required for publishing packages.

It should point at the root of your exposed web application, which is typically http://localhost:8080/openmrs during testing, but after being deployed will be something like http://192.168.1.100/openmrs or _http://yourdomainname.org/openmrs_. If it is empty or not filled in, you will not be able to get a URL after publishing a package.

Any URL prefix must start with http:// or https:// and cannot end with slash (/) .

Notifications 

If you want to be automatically notified about package updates, select the checkbox and enter how often the lookup for package updates should be performed. The number of days must be between 1 and 365.

After enabling notifications, whenever there is a new package version available, an alert will be displayed to users who have "Share Metadata" privilege:

Exporting Metadata

Creating new packages

Go to Administration → Metadata Sharing → Export Metadata

It is a list of previously created packages. The name, description and modification date come from the latest version of a package. The modification date is when the latest version of a package was created.

In order to export metadata go to Create package.

Add a name and a description to the package.
You can select here the checkbox to publish the package and include a URL in its content so that others can automatically subscribe to future updates while importing a zipped package.   There might be additional items (dependencies) that need to be included.  When done, click on next 

Click Add metadata to package and choose metadata you want to be included in the package.

You see the list of metadata types found in your system. You can either click Add all to include all metadata of the specific type or Choose individually.

If you click the latter, you will see the dialog listing all metadata of the chosen type. You need to select a checkbox in the Include column next to each metadata you want to include and confirm with the Save button. You can use the Search box to find metadata by name or uuid.

Review the chosen metadata. You can continue to add metadata with Add metadata to package or edit your previous choices in the Review chosen metadata section. If you finish, click Export

The newly created package can be found at the top of the list on the Manage Metadata Sharing page.  If you click on a link named package, it will take you to the Manage Metadata Sharing page. 

Creating new package versions 

Go to Administration → Metadata Sharing → Export Metadata

Click the name of a package for which you want to create a new version. 

Click Create new version from the latest version to start creating a new version with all metadata from the latest version automatically included. You can also create a new version starting from any of the previous versions by clicking   in the appropriate row. Metadata from the previous version can be removed as well as new metadata can be added. If some of metadata from the previous version are missing now, then warnings will be displayed, but you can ignore them and continue. All missing metadata will be automatically removed from the new package.  

Click Create new version starting from scratch to create a new version with no items from the previous version. 

Publishing packages

If a package is published, it can be imported from a designated URL. Additionally, when you create a new version of a package, everyone who is subscribing to the URL will be automatically notified about the update.

You can publish a package during its creation by selecting the appropriate checkbox:

If you do this, the package will contain the publish URL so that others can automatically subscribe to future updates while importing the zipped package. 

You can also unpublish ( ) and publish ( ) a package by clicking icons next to the choosen versions. The package content is immutable thus the publish URL will not be included in the package or removed at this step. It can be only done during creation.  

When at least one version of a package is published, you will be able to share the publish URL with others to allow them to download the latest published version from your server. It is not yet possible to download other published versions than the latest.

Importing Metadata

Finding packages

Please see Form Bank for HTML Entry Forms that are publicly available for download.

Importing packages

Go to Administration → Metadata Sharing → Import Metadata → Import package

You can import metadata either by uploading a zipped package or by pasting a URL of a published package. If you paste the URL then the latest available package version will be downloaded.

Next you will be required to choose the trust level:  

If you choose Require Confirmation, you will be asked to review most of metadata before importing. The Trust Incoming option in most cases will default to overwrite your existing metadata and will not require confirmation. Click Next to proceed.

At this step you can review the package header. You will be warned if the package was exported with a different version of OpenMRS. For instance it is not possible to import a package with Concepts exported from 1.6.x to 1.7.x. The warning will be also displayed if you import an old version of a package that was previously imported.

If you import a package from a URL or if a zipped package contains the publish URL, you will be able to subscribe to future package updates. 

Click Next.

 It is a summary of items included in the package. Each item has an associated action. You are required to assess (confirm) some of the actions. You can do so by clicking the Start assessing button. Most of the time you can choose from the following actions:

• Create New - Create a new item in the system.
• Skip If Possible - Skip importing this item, if there are no other items which require this item to work.
• Keep Mine - Leave your existing item unchanged. May cause problems in other imported items if your item doesn't have compatible properties (e.g. datatype, answers).
• Overwrite - Overwrite your existing item with the incoming one. May cause problems in existing data.

The default action is chosen upon the following rules:

1. If you already have the same UUID:
   1. If date-modified is the same: Skip if Possible with no confirmation
   2. If you chose Trust Incoming: Overwrite with no confirmation
   3. If you chose Require Confirmation:
      1. If incoming is newer: Overwrite with confirmation
      2. If existing is newer: Keep Mine with confirmation
      3. If cannot determine dates: Keep Mine with confirmation
2. If you have something mapped for this UUID: (means we've previously done a Keep Mine or Overwrite)
   1. If date-modified is the same: Keep Mine with no confirmation
   2. Otherwise: the same action as previously with confirmation
3. If you have something with the same name: Keep Mine with confirmation
4. If incoming fails validation: Skip If Possible with confirmation

You can change the default action by clicking assess next to each item. There are two versions of an assess screen.

You will see this screen if you already have an item with the same UUID. You can only choose to Keep Mine or Overwrite.

You will see this screen in other cases. It allows you to choose Create New, Skip If Possible, Choose Existing / Keep Mine or Choose Existing / Overwrite.

Some of the options may be disabled. For instance if an incoming item fails validation in your system, you cannot choose Create New. However, you can try to resolve the validation error and return to the item later, skip or choose a replacement.

If the module finds an existing item that has the same name, it'll be automatically suggested to you. You can always choose a different replacement by clicking Choose replacement.

Click Choose in this dialog to select a replacement for the incoming item.

You see that the existing item is now chosen. Click Next to see the next item that needs assessment. You will be taken back to the summary screen if there are no more items that need assessment.

Click Import at the bottom of the summary screen.

Preserving Internal Id Numbers

Occasionally an admin might want to try to keep the same database primary key numbers from the exporting server. As of version 1.0 internal primary keys are exported and it is up to the importing server if they should be kept (by default they are ignored).

Modify the setting "metadatasharing.persistIdsForClasses" to include the package name and class name for the objects you want to persist ids for. e.g. org.openmrs.Concept, org.openmrs.ConceptSource, org.openmrs.Form, org.openmrs.EncounterType.

If the id already exists when importing, the id is reset to blank and will be added to the end of the list of concepts. E.g. importing a concept with id 4 in a db with 1000 concepts, but concept 4 already exists, so this concept will now have id 1001 on this system.

Typically internal primary key ids do not matter, but for some modules (like formentry), they depend on the form and concept ids to match up, so this is helpful.

Updating packages

Go to Administration → Metadata Sharing → Import Metadata

You will see here a list of subscriptions. You can check if there are any updates available by clicking Check for updates button on the top. It is also available to check for updates for a single subscription by clicking Check now link next to it.

If there are any updates available, then a status cell has a yellow background and you can choose to Apply update by clicking the link. This will trigger the package import process. 

The status cell with a green background means that there is no new version available on the server. 

The status cell with a red background means that there were some errors while checking for updates and if the reason is known a message is displayed to the user. 

Fetching packages on the fly via the metadata REST webservice

The module provides a REST web service exposing an API. Currently, only one operation is provided i.e to fetch a package from a remote server, both GET or POST are supported.

Packages can be fetched either programmatically or by entering the appropriate url with the expected request parameters in the browser and your will get the download prompt. Packages can be fetched as plain text or as a zip file.

Associated global properties

• metadatasharing.enableOnTheFlyPackages - Specifies whether metadata packages can be exported on the fly, i.e enables/disables the module's web service
• metadatasharing.webservicesKey - Security key to grant access to remote systems to consume the module's web service, if null or blank, no key will be required from the consumers of the web service

Supported Request Parameters

• key - Required if server has it is defined on remote system. The secret key to send along with every request to be granted access to the web service
• type - Required. This is the fully-qualified class name of the type of object you wish to import
• uuids - List of uuids for the items to import (you may specify either uuids, ids, or both)
• ids - List of ids for the items to import (you may specify either uuids, ids, or both)
• modifiedSince - (Date format = dd/mm/yyyy) When specified, items to be returned should have been created or modified after the specified date

URL Format

[url-to-server]/ws/rest/metadatasharing/package/new.form?&[requestParameters]

Example of the URL

http://localhost:8080/openmrs/ws/rest/metadatasharing/package/new.form?&type=org.openmrs.Location&ids=1,2&uuids=5b635b8d02812d2e1c97691cd71fc05a&modifiedSince=01/01/2012