Synchronise structural metadata between FMR environments

Overview

The Fusion Metadata Registry provides the means to synchronise its structural metadata contents with that of another Registry instance. On synchronisation, the Registry will display a list of all the differences and offer the user the opportunity to push local changes to the target Registry or pull changes in from the target Registry.

Defining a target

To create a new synchronisation target, first log into the Fusion Registry as a user with Admin privileges and click on the on the Environments menu item in the sidebar to open the page shown below.

To add an environment, click the Add button and then identify it as shown in the example below.

The Environment will now be shown in the environments page as shown below.

Synchronise Structures

To perform a synchronisation, navigate to the Environments page, and select the target environment to synchronise with and click the Synchronise button. The local Registry will query for the contents of the target Registry and perform a check of its contents against the local contents. The result will show a list of all the differences between the two environments. Each change is categorised by whether it is incoming, outgoing, or a conflict.

Options Available

Synchronisation options include PULL and PUSH, where a Pull results in importing a structure from the target environment to the local environment and a Push results in the local structure being submitted to the target environment.

A Pull does not require authentication as the Pull action will be verified against the credentials of the currently authenticated user. A Push requires authentication against the target environment. The credentials of an Agency user or Admin user must be used, with the target environment performing authentication and authorisation.

In addition, when a Pull or Push is performed, the following sync options will be presented allowing the choice of the following actions:

Selected structures only

Only Pull/Push the selected structure(s).

Note: if there are any cross-referenced structures that do NOT exist in the local registry, the pull will fail.

Selected structures and descendants

Pull/Push the selected structure(s) and include all the cross-referenced structures. For example, a pull on a Dataflow will include the referenced Data Structure Definition, Codelists, Concepts, and Agency Schemes in the pull.

Any structures that exist in the local Registry will be overwritten with those from the target environment.

Selected structures merge descendants

Pull/Push the selected structure(s) and include all the cross-referenced structures, for example a pull on a Dataflow will include the referenced Data Structure Definition, Codelists, Concepts, and Agency Schemes in the pull.

Any item schemes (Codelists, Concepts, Agency Scheme, Data Provider Scheme, Data Consumer Scheme) that exist in the local Registry will be merged with those from the target environment. For example if the target environment has a new code in a Codelist, the local Codelist will be updated to include the new code, whilst preserving any existing differences in the local Codelist.

Full Replace

Replace the contents of the Registry with those being pulled/pushed. Any structures in the target environment which are not included in the pull or push will be removed from the target environment.

Note: This is only relevant if the full environment is pulled or pushed, as described below

Full Sync

To perform a full sync select the top level label in the Sync result tree, as shown below. Then click the action of Push or Pull to either submit all the structures to the target or import them locally.

To perform a full sync on all structures of a specific type, click on the Structure Type in the hierarchy followed by Push or Pull as appropriate. In the example below, selecting Codelists at this level would Push or Pull all Codelists.

Incoming Changes (Pull)

Incoming changes are denoted by a green chevron pointing to the left (<). This indicates that the structure exists in the target environment, and not in the local environment. Performing a pull on this structure will result in the structure being imported into the local Fusion Registry. A single structure can be pulled by checking the checkbox next to the structure, or if multiple checkboxes are selected then multiple structures can be pulled at once.

Outgoing Changes (Push)

Outgoing changes are denoted by a blue chevron pointing to the right (>). This indicates that the structure exists in the local environment, and not in the target environment. Performing a push on this structure will result in the structure being submitted to the local Target Registry.

A single structure can be pushed by checking the checkbox next to the structure, or if multiple checkboxes are selected then multiple structures can be pushed at once. A push action requires authentication with the target server, so a username and password are required.

On clicking Push the same Sync Options as the Pull action will be displayed and have the same meaning as described above - Options.

Conflicts

Conflicts are denoted by a double red arrow. This indicates that the structure exists in both the local environment and the target environment, but with differences in the structure’s content between the environments. A conflicting structure can be pushed to the target (overwrite the target’s version) or pulled to the local environment (overwrite the local version). For the case of item schemes (Codelists, Concepts, Agency Scheme, Data Provider Scheme, Data Consumer Scheme) individual items can be pulled or pushed, as explained in the following section.

Push or Pull an individual item

For items in item schemes, this includes Codelists, Concepts, Agency Scheme, Data Provider Scheme, Data Consumer Scheme, the individual items can be pushed or pulled. To perform this action, ensure there are no checkboxes selected. Click on the item scheme (for example the Codelist) and then click Sync Items. A list of all the items with the relevant incoming, outgoing, or conflicting icons will be shown, as demonstrated in the image below.

The same actions can be performed on the individual items, allowing for partial lists to be pulled or pushed between environments.