Chapter 29. Synchronizing metadata

Table of Contents

29.1. About metadata synchronization
29.2. Metadata Sync Task
29.3. Authorities to sync and create versioned metadata
29.4. Configure Central Instance
29.5. Configure Local Instance
29.6. Steps to sync metadata
29.7. Best Practices at Central Instance
29.8. Best Practices at Local Instance

29.1. About metadata synchronization

Metadata versioning:

Metadata is "data about data". In the context of DHIS2, metadata consists of definitions of data elements, indicators, the structure and names contained in the organizational hierarchy, and other options.

Users can create or modify metadata at any point of time and save them in DHIS2 using Metadata Synchronization feature added from 2.24. The process on how to use this feature is explained in subsequent sections of this chapter.

Given the above deployment strategy there is a dire need to ensure that all the field instances are up to date with a common metadata model. The central instance is the common data warehouse for the local instances. All the data collected at the local instances is pushed to the central instance for analysis and decision making. Metadata sync enables the local instances to interact with the central instance to get the metadata versions in the same order in which they get created. In case of multiple local nodes the need to effectively track the version at which they are, is imperative.

The metadata simply gets created at one central instance and all the local instances would download the metadata at their convenience. The local systems can request the download of metadata at any point of time and hence it makes sense to store all the metadata created in the central system.

Each snapshot of metadata export generated is referred as a Metadata Version. The new version created would contain only the new changes from the previous version to the current one. i.e...It is an export between two timestamps. All of these versions are maintained in the DHIS2 database itself and would be available to all the local instances who would connect to this central system. The local instances would simply need to connect to this central system and download/import metadata to their system rather than creating the same metadata all over again.

Users can select the type of metadata which needs to be created. Metadata Version type governs how the importer should treat the given version. This type will be used while importing the metadata. There are two types of metadata.

  • BEST_EFFORT - This type suggests that missing references can be ignored and the importer can continue importing the metadata (for example missing data elements on a data element group import)

  • ATOMIC - ensures a strict type checking of the metadata references and the metadata import will fail if any of the references do not exist.

Metadata Sync:

The process of connecting to a central system for downloading and then importing metadata to local system is referred to as Metadata Synchronization. The feature to synchronise metadata created in one system to another in a seamless fashion is now available at just a click of a button. Till now for this purpose, users need to use the Import-Export functionality for metadata in DHIS2.

This new feature automates the export-import actions without any manual intervention from the user. Metadata will be created at only one system(central) and all other instances(fields) can sync the metadata from it. But metadata scheduling needs to be enabled at the field. In this way, we can ensure the metadata is same and up-to-date across all the systems and the consistency across all the systems can be maintained more effectively.


Users can still use the existing Export/Import actions if they need to sync metadata manually.