Synchronize DHIS2 Metadata¶
After connecting and testing your DHIS2 connection, synchronize the DHIS2 metadata that FieldOps needs to configure the integration.
Metadata synchronization brings the relevant DHIS2 configuration into FieldOps so that users can map sites, select indicators, and configure project performance monitoring without manually entering DHIS2 IDs.
Before you begin¶
You need:
- An active DHIS2 connection in FieldOps
- A successfully tested DHIS2 connection
- Permission to manage DHIS2 integrations in your FieldOps organization
Note
Metadata synchronization uses the DHIS2 connection credentials already configured in FieldOps. You do not need to enter your DHIS2 credentials again when synchronizing metadata.
What metadata is synchronized?¶
FieldOps synchronizes the following DHIS2 metadata:
- Organization units
- Data elements
- Data sets
- Data set-to-data-element relationships
- Indicators
This metadata is stored in FieldOps and used to configure the DHIS2 integration.
Step 1: Open DHIS2 Connections¶
Sign in to FieldOps and open DHIS2 Connections from the application navigation.
Locate the DHIS2 connection you want to synchronize.
Note
Your organization can have more than one DHIS2 connection. Make sure you select the connection that contains the DHIS2 data you want to use.
Step 2: Synchronize metadata¶
Open the DHIS2 connection and select the action to synchronize DHIS2 metadata.
FieldOps will connect to the configured DHIS2 server and retrieve the available metadata.
The synchronization includes:
- DHIS2 organization units
- DHIS2 data elements
- DHIS2 data sets
- Data set-to-data-element relationships
- DHIS2 indicators
The synchronization is performed in this order because some DHIS2 metadata depends on other metadata.
Organization units¶
FieldOps synchronizes DHIS2 organization units so they can later be mapped to FieldOps sites.
For each organization unit, FieldOps can retain information such as:
- DHIS2 ID
- Name
- Short name
- Code
- Level
- Hierarchical path
- Parent organization unit
- Original DHIS2 metadata
For example:
DHIS2 organization unit
Nairobi Central Clinic
This organization unit can later be mapped to the corresponding FieldOps site.
Data elements¶
FieldOps also synchronizes DHIS2 data elements.
Data elements are used by DHIS2 data sets and are part of the metadata required to understand the DHIS2 reporting structure.
Note
Data elements are synchronized as DHIS2 metadata. They are not automatically added as project indicators.
Data sets¶
FieldOps synchronizes DHIS2 data sets together with their relationships to data elements.
This allows FieldOps to retain the structure of the DHIS2 reporting configuration.
For example, a DHIS2 data set may contain several data elements representing different measures reported by health facilities.
Indicators¶
FieldOps synchronizes DHIS2 indicators so they can be selected when configuring a project.
Indicators are particularly important for project performance monitoring because they provide the measures that FieldOps can compare against project-specific targets.
Note
Synchronizing indicators does not automatically add every indicator to every project. Project indicators are configured separately.
Synchronization result¶
After the synchronization completes, FieldOps provides a summary of the metadata synchronized.
The summary includes counts for:
- Organization units
- Data elements
- Data sets
- Data set-to-data-element relationships
- Indicators
For example:
| Metadata | Synchronized |
|---|---|
| Organization units | 125 |
| Data elements | 480 |
| Data sets | 24 |
| Data set relationships | 1,240 |
| Indicators | 85 |
The actual numbers depend on the DHIS2 instance and the metadata available to the connected account.
Last synchronized time¶
FieldOps records the time of the most recent successful DHIS2 metadata synchronization.
This information is available through the DHIS2 connection and is also used by the project's DHIS2 Sync Health section.
Note
The synchronization timestamp is updated when the complete metadata synchronization succeeds. It is not updated by individual metadata synchronization steps.
If a synchronization fails before completion, FieldOps does not treat the operation as a successful metadata synchronization.
Synchronizing again¶
You can synchronize metadata again when the DHIS2 configuration changes.
For example, you may need to synchronize again when:
- New organization units have been created in DHIS2
- Organization unit names or other metadata have changed
- New data elements have been added
- Data sets have changed
- New indicators have been created
- Existing indicators have been updated
- DHIS2 reporting configuration has changed
Running the synchronization again updates the corresponding metadata already stored in FieldOps.
Tip
Synchronize metadata before configuring new DHIS2 projects so that the latest organization units and indicators are available for configuration.
Metadata synchronization and reporting data¶
Metadata synchronization is different from synchronizing DHIS2 reporting data.
Metadata synchronization retrieves the DHIS2 configuration required to set up the integration.
Reporting data synchronization retrieves the actual DHIS2 values used for project performance monitoring.
The general workflow is:
- Connect DHIS2.
- Test the connection.
- Synchronize DHIS2 metadata.
- Map FieldOps sites to DHIS2 organization units.
- Configure project indicators and targets.
- Synchronize DHIS2 reporting data.
- Review project performance.
Note
Synchronizing metadata does not by itself populate project performance values. Reporting data must be synchronized separately.
If synchronization fails¶
If metadata synchronization fails, check the following:
- The DHIS2 connection is active
- The DHIS2 server is accessible
- The configured username and password are correct, if using username and password authentication
- The configured Personal Access Token (PAT) is correct, if using PAT authentication
- The DHIS2 account has permission to access the required metadata
- The DHIS2 Base URL is correct
- The DHIS2 instance is available
You can also use Test Connection to confirm that FieldOps can communicate with the DHIS2 server.
Warning
Do not change DHIS2 connection credentials unnecessarily when troubleshooting metadata synchronization. First use Test Connection to determine whether the connection itself is working.
What to do next¶
Once metadata synchronization has completed successfully, you can map your FieldOps sites to DHIS2 organization units.