Connect ODK Central¶
Connect an ODK Central server to FieldOps to synchronize form submission data into your FieldOps operational workflows.
After creating a connection, you can create a separate ODK Form Mapping to associate an ODK Central form with the appropriate FieldOps Programme, Project, Site, and optionally a Monitoring Template.
Before you begin¶
You need:
- Access to the ODK Central server you want to connect
- Your ODK Central server URL
- The ODK Central Project ID containing the forms you want to use
- An ODK Central account with access to the required project and forms
- The email address used to sign in to ODK Central
- The password for the ODK Central account
- Permission to create integrations in your FieldOps organization
Note
The ODK Central account used for the connection must have access to the project and forms you want FieldOps to synchronize.
Step 1: Identify your ODK Central server URL¶
The Base URL is the address you normally use to access your ODK Central server.
For example:
https://odk.example.org
Enter the main server address without adding API paths or form-specific URLs.
For example, use:
https://odk.example.org
Do not use:
https://odk.example.org/v1/projects/1/forms/example
Tip
If you are unsure which Base URL to use, open ODK Central in your browser and use the main address of your Central server.
Step 2: Find your ODK Central Project ID¶
FieldOps requires the ID of the ODK Central project containing the forms you want to synchronize.
Open the project in ODK Central and look at the URL in your browser.
The URL will contain the Project ID.
For example:
https://odk.example.org/#/projects/1/forms
In this example, the Project ID is:
1
Copy the number that appears after /projects/ and enter it into the Project ID field when creating the ODK connection.
Tip
The Project ID is usually a number, such as 1, 2, or 15.
Warning
Enter only the Project ID. Do not enter the complete ODK Central URL into the Project ID field.
Step 3: Confirm your ODK Central credentials¶
FieldOps connects to ODK Central using an ODK Central user account.
You will need:
- Email address — the email address used to sign in to ODK Central
- Password — the password for that ODK Central account
The account should have access to the ODK Central project and forms that you plan to use with FieldOps.
Warning
Treat your ODK Central credentials as sensitive information. Do not include passwords in screenshots, support messages, or documentation examples.
Step 4: Open ODK Connections in FieldOps¶
Sign in to FieldOps and open ODK Connections from the application navigation.
Select the action to create a new ODK Central connection.
Step 5: Enter the connection details¶
Complete the connection form with the details for your ODK Central server and project.
Enter:
- Connection name — a descriptive name that helps users identify the connection
- Base URL — the address of your ODK Central server
- Email address — the email address of the ODK Central account
- Password — the password for the ODK Central account
- Project ID — the numeric identifier of the ODK Central project containing the forms you want to use
Connection name¶
Use a clear name, especially if your organization may connect more than one ODK Central server, project, or account.
For example:
- Production ODK Central
- Kenya Programme ODK
- Regional Monitoring Central
Base URL¶
Enter the main address of your ODK Central server.
For example:
https://odk.example.org
Do not include a project ID, form ID, submission endpoint, or other API path.
Email address¶
Enter the email address used to sign in to the ODK Central account that has access to the required project and forms.
Password¶
Enter the password for the ODK Central account.
Warning
Use an account that your organization is authorized to connect to FieldOps. Do not share the account password with users who do not require access to the ODK Central connection.
Project ID¶
Enter the numeric ID of the ODK Central project containing the forms you want to use with FieldOps.
For example:
1
If the ODK Central project URL is:
https://odk.example.org/#/projects/1/forms
the Project ID is:
1
Note
An ODK Connection in FieldOps is associated with a specific ODK Central project. If you need to connect forms from another ODK Central project, create another connection using that project's Project ID.
Step 6: Test and create the connection¶
Before saving the connection, select Test Connection.
FieldOps will use the supplied Base URL, credentials, and Project ID to test whether it can successfully connect to the specified project on your ODK Central server.
If the connection is successful, FieldOps will display a success message.
You can then select Create to save the connection.
Tip
Always use Test Connection before creating the connection. This helps confirm that the Base URL, email address, password, and Project ID are correct.
If the connection test fails, review:
- The Base URL
- The Project ID
- The email address
- The password
- Whether the ODK Central account has access to the specified project
Correct any problems and select Test Connection again.
Once the test is successful, select Create to save the connection.
The connection will then be available under ODK Connections.
Security considerations¶
The ODK Central credentials used for the connection may provide access to sensitive field data.
To protect the connection:
- Use an authorized ODK Central account
- Limit the account's access to the projects it requires where possible
- Do not share the account password unnecessarily
- Do not include credentials in screenshots
- Update the FieldOps connection if the ODK Central password changes
- Remove connections that are no longer required
Warning
Never include a real ODK Central password in a support ticket, public message, screenshot, or documentation example.
Using multiple ODK Central connections¶
Your organization may create multiple ODK Central connections if your FieldOps plan and permissions allow it.
Multiple connections may be useful when:
- Different programmes use different ODK Central servers
- Different ODK Central projects need separate connections
- Different partners manage separate ODK Central deployments
- Development and production environments are separated
- Different ODK Central accounts provide access to different projects
Use descriptive connection names so that users can identify the correct connection when creating a form mapping.
Common problems¶
FieldOps cannot connect to ODK Central¶
Check that:
- The Base URL is correct
- The Project ID is correct
- The email address is correct
- The password is correct
- The ODK Central account is active
- The account has access to the specified project
- The account can sign in to the ODK Central server
- The server is accessible
- Your organization has not reached its ODK connection limit
The Base URL is not working¶
Make sure you entered the main ODK Central server address.
For example:
https://odk.example.org
Do not enter a URL containing:
/v1/- A Project ID
- A Form ID
- A submission endpoint
The Project ID is not working¶
Open the project in ODK Central and check the URL in your browser.
For example:
https://odk.example.org/#/projects/1/forms
The Project ID is the number after /projects/.
In this example:
1
Check that:
- You entered only the numeric Project ID
- You did not enter the complete project URL
- The ODK Central account used by the connection has access to that project
The credentials previously worked but now fail¶
The ODK Central password may have changed, or the account may no longer have access to the server or project.
Confirm that the account can still sign in directly to ODK Central and access the specified project.
Update the connection details in FieldOps if necessary.
What to do next¶
Creating an ODK Central connection allows FieldOps to communicate with a specific project on your ODK Central server.
The next step is to create an ODK Form Mapping.
The form mapping identifies the ODK Central form within the connected project and associates it with the appropriate FieldOps:
- Programme
- Project
- Site
- Monitoring Template, if applicable