Synchronization Rules
- Create a rule
- Rules options
- MD Sync and the DHIS2 user roles
- Extra: Setup the system to schedule mdsync rules
A rule is a synchronization operation stored to be used more than once. They can be executed manually or scheduled to be executed at regular time intervals. They are helpful when data needs to be transferred from the source to the destination instance at regular time intervals or when we need to keep certain types of metadata (e.g. OU) constantly synchronized across instances.
You can create a rule for each kind of synchronization:
- Metadata
- Aggregated data
- Events
From the MD Sync main panel, go to "Sync rules" to view existing rules, edit them or create new ones.
A rule can be created in two different ways:
- By clicking on the ADD RULE button within the screen with list of rules
- When you are creating a Manual Sync, at the last step of the process there is option to save it as a rule
To create a rule, you need to follow the same process as for executing a one time synchronization plus two extra steps: assigning a name to the rule and scheduling.
in this section we focus on the additional steps.
The first step for creating a rule is adding its name and description. Feel free to name it as you want, but It is advisable to give rules a concise and self-explanatory name for easy identification within the rule list. Follow a clear pattern within your team and add a description if necessary.
In this option you configure the periodicity at which the rule will be executed. To define that periodicity, we use a syntax that you might know from UNIX administration: "Cron" syntax. A Cron expression is a string comprising six fields separated by white space that represents a routine.
Read the details about Cron expressions here
S M H DM MO DW
S= Second (0 - 59)
M = Minute (0 - 59)
H = Hour (0 - 23)
DM = Day of the month (1 - 31)
MO = Month (1 - 12)
DW = Day of the week (1 - 7) (Monday to Sunday)
An asterisk (*) matches all possibilities. For instance, if we want to run a rule every day, we would use asterisks for day of the month, day of the week, and month of the year to match all values.
A wildcard (?) means no specific value and only works for day of the month or day of the week. For example, if you want to execute a rule on a particular day (10th) but you don't care about what day of the week that is, you would use ? in the day of the week field.
To make your life easier with Cron expressions, each time you edit the rule we translate it into "human readable language" For instance if you type:
1 10 0 1 * *
We also display that it means a synchronisation that runs:
At 12:10:01 AM, on day 1 of the month
You can create your custom Cron expression or use one of the predefined templates for daily, monthly yearly scheduling...
The list of rules has this list of options (right click or three dots menu)
Most of them are obvious, only sharing settings requires further explanation.
- Details: displays information about the rule
- Edit: Allows you to modify the rule.
- Delete: Permanently remove the rule.
- Execute: Run the rule once.
- Download JSON: The JSON file with the data/metadata in that rule, as described here
- Replicate: Creates a copy of the rule.
- Toggle scheduling: Turns on and off the scheduling. When a rule has a schedule, you can disable it with this option.
- Sharing settings: Configure the permissions for the rule. Read more in the following section.
→ Synchronization rules/ rule/ three points menu / sharing settings
Special attention should be given to the sharing settings when one instance is shared between different organizations or departments. Rules are public by default. If you do not configure sharing settings, it might happen that people without access to some kind of metadata can run the rule affecting to that metadata.
-
Example scenario
There is a DHIS2 instance shared by two programs with its own users: malaria and hepatitis. The users with access to malaria metadata don't have access to hepatitis metadata, and vice versa. In this situation a user from the malaria group, cannot create a rule using hepatitis metadata. But if that rule exists, and it has public access, that user could run the rule. To avoid that situation, the sharing settings for your rule needs to be configured.
There are three access levels for a synchronization rule:
- Edit and view: can edit the rule and run
- View: can run the rule
- No Access
And you can set the access level to:
- Public access (all users within the instance)
- Individual users
- Groups of users
- (External access appears only for compatibility reasons. It is disabled)
For instance you can configure a single user that can edit a rule and at the same time a group which can view and run a rule but not edit it.
with this combination of users and levels, different groups of users can view and execute only a subset of rules, avoiding different user groups to interfere in each others' processes.
In MD Sync user inherit the permissions they have in DHIS2 core. Hence, a user in the source instance cannot include any metadata object he/she does not have access to in any synchronization:
MD Sync provides two different additional roles (Additional to those define already by DHIS2 core)
- MetaData Sync executor: Users with this role can only execute sync rules. They cannot execute manual synchronizations or create new sync rules
- MetaData Sync configurator: Users with this role can execute manual synchronizations, create and rune sync rules.
TBD
