Connect DHIS2¶
Connect a DHIS2 instance to FieldOps so that your organization can synchronize DHIS2 metadata and use DHIS2 reporting data within FieldOps project workflows.
FieldOps supports two authentication methods when creating a DHIS2 connection:
- Username & Password
- Personal Access Token (PAT)
Choose the authentication method supported by your DHIS2 environment.
Before you begin¶
You need:
- Access to the DHIS2 instance you want to connect
- The DHIS2 server URL
- Either:
- A DHIS2 username and password, or
- A DHIS2 Personal Access Token (PAT)
- Permission to create integrations in your FieldOps organization
Note
Your DHIS2 account must have sufficient permissions to access the metadata and reporting data that you want FieldOps to synchronize.
Step 1: Open DHIS2 Connections¶
Sign in to FieldOps.
Open DHIS2 Connections from the application navigation.
Select the action to create a new DHIS2 connection.
Step 2: Enter the connection details¶
Complete the connection form using the details for your DHIS2 instance.
FieldOps requires:
- Connection name — a descriptive name for the DHIS2 connection
- Base URL — the URL of the DHIS2 server
- Authentication method — how FieldOps should authenticate with DHIS2
For authentication, choose either:
- Username & Password
- Personal Access Token (PAT)
Step 3: Enter the DHIS2 Base URL¶
Enter the URL of the DHIS2 server you want to connect to.
For example:
https://dhis.example.org
The Base URL should point to the DHIS2 server, not to a specific API endpoint.
Tip
If your DHIS2 server is available at https://dhis.example.org, enter https://dhis.example.org as the Base URL rather than adding /api or another API path unless your DHIS2 deployment specifically requires it.
Step 4: Choose an authentication method¶
FieldOps allows you to select the authentication method when creating the connection.
Option 1: Username & Password¶
Select Username & Password if you want FieldOps to authenticate using a DHIS2 user account.
Enter:
- Username
- Password
The DHIS2 user should have the permissions required for the data FieldOps needs to access.
Warning
Use a dedicated DHIS2 service account where possible rather than a personal user account. This makes the integration easier to manage when team members change.
Warning
Never include your DHIS2 password in screenshots, support tickets, documentation, or public messages.
Option 2: Personal Access Token (PAT)¶
Select Personal Access Token (PAT) if your DHIS2 environment provides and permits the use of Personal Access Tokens.
Enter the PAT provided by your DHIS2 instance.
Warning
Treat your Personal Access Token like a password. Do not share it publicly or include it in screenshots, documentation, or support requests.
Note
The availability and configuration of Personal Access Tokens depends on your DHIS2 version and deployment.
Step 5: Choose the appropriate authentication method¶
Use the authentication method that matches how your DHIS2 environment is configured.
| Authentication | When to use |
|---|---|
| Username & Password | Your DHIS2 integration account uses standard DHIS2 credentials |
| Personal Access Token (PAT) | Your DHIS2 environment provides a PAT and you prefer token-based authentication |
You do not need to configure both methods for the same connection.
Tip
If you are unsure which method to use, check with your DHIS2 administrator. They can confirm whether your DHIS2 environment supports Personal Access Tokens and which authentication method is recommended.
Step 6: Save the connection¶
After entering the connection details, select Create.
FieldOps will save the DHIS2 connection.
The connection will then appear under DHIS2 Connections.
Step 7: Test the connection¶
Open the newly created DHIS2 connection and select Test Connection.
FieldOps will attempt to connect to the DHIS2 server using:
- The configured Base URL
- The selected authentication method
- The supplied credentials or PAT
If the connection succeeds, FieldOps records the connection as Connected.
If the connection fails, FieldOps records the connection as Failed and stores the connection error message.
A connection that has not yet been tested can remain in an Unknown state.
Tip
Always use Test Connection before attempting to synchronize metadata. This confirms that FieldOps can communicate with the DHIS2 server using the supplied authentication details.
Connection status¶
FieldOps tracks the most recent DHIS2 connection test.
The connection status can be:
Connected¶
The most recent connection test was successful.
Failed¶
The most recent connection test failed.
Review the connection message and verify:
- The Base URL
- The authentication method
- The username and password, if using username authentication
- The PAT, if using PAT authentication
- The DHIS2 server availability
- The permissions of the DHIS2 account
Unknown¶
The connection has not yet been successfully tested or does not currently have a recorded connection status.
Note
Connection status and synchronization status are different. A connection can be successfully tested while DHIS2 metadata has not yet been synchronized.
Using multiple DHIS2 connections¶
A FieldOps organization can have multiple DHIS2 connections.
This can be useful when an organization works with different DHIS2 environments or systems.
For example:
- Different programs use different DHIS2 instances
- Development and production DHIS2 environments are separated
- Different partners operate separate DHIS2 servers
- A regional organization works with multiple country-level DHIS2 instances
- Different projects use different DHIS2 environments
FieldOps therefore does not assume that one organization has only one DHIS2 connection.
Note
Projects use the DHIS2 connections associated with the DHIS2 mappings of their sites. This allows an organization to work with multiple DHIS2 sources without forcing every project to use the same DHIS2 instance.
Security considerations¶
DHIS2 credentials and Personal Access Tokens can provide access to sensitive reporting data.
To protect your connection:
- Prefer a dedicated DHIS2 service account for integrations
- Give the DHIS2 account only the permissions it requires
- Do not share passwords or PATs unnecessarily
- Never include credentials in screenshots or documentation
- Rotate credentials or tokens according to your organization's security policies
- Remove connections that are no longer required
Warning
Never paste a real DHIS2 password or Personal Access Token into a support ticket, public message, screenshot, or documentation example.
Common problems¶
FieldOps cannot connect to DHIS2¶
Check that:
- The Base URL is correct
- The DHIS2 server is accessible
- The selected authentication method is correct
- The username and password are correct, if using username authentication
- The PAT is valid, if using PAT authentication
- The DHIS2 account has the required permissions
- The DHIS2 server is not blocking requests from FieldOps
Then select Test Connection again.
Username and password authentication fails¶
Verify:
- The username is correct
- The password is correct
- The DHIS2 account is active
- The account is not locked or disabled
- The account has permission to access the required DHIS2 resources
PAT authentication fails¶
Verify:
- The PAT is correct
- The PAT has not expired or been revoked
- The PAT belongs to an active DHIS2 user
- The associated user has the required permissions
- Your DHIS2 deployment supports the PAT authentication method
The connection works but synchronization fails¶
A successful connection test confirms that FieldOps can authenticate with DHIS2. It does not necessarily mean that the account has permission to access every type of metadata or reporting data required by FieldOps.
Check the DHIS2 user's permissions and then review the synchronization process.
What to do next¶
After successfully connecting and testing DHIS2, synchronize the metadata that FieldOps needs for the integration.