Understanding Metadata Sync flow

The Metadata Sync facility in DHIS2 can be used to synchronize data and metadata between different DHIS2 instances. Occasionally issues do occur which requires manual intervention to resolve.

To aid in this manual intervention, the processes involved in the synchronization process is described below:

To force or prevent certain metadata versions from being synced, some changes can be effected in the database, which will impact the decision being taken at certain stages within the flow. Two of the key database tables on which decisions are taken are:

  • metadataversion
  • keyjsonvalue

The records in this table can be manipulated accordingly to influence some of the decisions that will be taken when metadata sync takes place.

How to bypass syncing certain metadata versions

  1. Insert the required records for the metadata versions to be bypassed into the metadataversion table of the local instance. You can export these records from the metadataversion table of the remote instance, and import into the local instance.
  2. Update keySystemMetadataVersion key in the systemsetting table to the latest metadata version that will be bypassed.

How to export specific keyjsonvalue records from the remote DHIS2 instance

  1. Create an SQL view query for selecting the desired records from the remote DHIS2 instance.The query above selects the records for metadata versions 174 - 176.
    • sql SELECT jbvalue::varchar,keyjsonvalueid,uid,code,created,lastupdated,namespace, namespacekey,encrypted_value,encrypted,publicaccess FROM keyjsonvalue WHERE namespacekey IN ('Version_174', 'Version_175', 'Version_176');
  2. Execute the SQL view
  3. Export as CSV
  4. In the exported CSV file, replace all commas in the header and column records with ;, as that is the delimiter that will be used in the SQL query that will be used for the import.

How to update the missing metadata payload in the local instance database

It is assumed the the previous step has already been performed to obtain the CSV file that will be imported into the local instance to fix the missing metadata payload.

  1. On the local instance, import the missing metadata into the keyjsonvalue table (using psql)
    • java \COPY keyjsonvalue (jbvalue,keyjsonvalueid,uid,code,created,lastupdated, namespace,namespacekey,encrypted_value,encrypted,publicaccess) FROM 'C:\\<path-to-the-csv-file>\\missing-records.csv' WITH DELIMITER ';' CSV HEADER;
  2. Verify that the missing records have been added to the database (using psql)
    • java SELECT namespace, namespacekey FROM keyjsonvalue WHERE namespacekey IN ('Version_174', 'Version_175', 'Version_176');
  3. Try to download any of the record(s) for valid JSON structure inspection. For example, we can attempt to download metadata version 174 which was earlier imported by visiting the following URL: http:///api/metadata/version/Version_174/data.gz
  4. Unzip any/all of the downloaded archives to verify that the metadata downloaded is a valid JSON structure.