Skip to content

ODK Central Troubleshooting

Use this guide to resolve common problems when connecting ODK Central to FieldOps, creating form mappings, or synchronizing submission data.

Connection problems

FieldOps cannot connect to ODK Central

If the connection test fails, check the connection details.

Confirm 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 ODK Central project
  • The ODK Central server is accessible

After correcting the connection details, select Test Connection again.

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 an ODK Central connection.

The Base URL is not working

Enter the main address of your ODK Central server.

For example:

https://odk.example.org

Do not enter:

  • An API endpoint
  • A project-specific API URL
  • A form URL
  • A submission URL

For example, do not use:

https://odk.example.org/v1/projects/1/forms/example

Use only:

https://odk.example.org

Tip

Open ODK Central in your browser and use the main server address as the Base URL.

The Project ID is not working

The Project ID identifies the ODK Central project containing the forms you want to use with FieldOps.

Open the project in ODK Central and look at the URL in your browser.

For example:

https://odk.example.org/#/projects/1/forms

The Project ID is:

1

Enter only the number into the Project ID field.

Check that:

  • You entered only the Project ID
  • You did not enter the complete project URL
  • The Project ID belongs to the ODK Central server configured in the connection
  • The connected ODK Central account has access to the project

Warning

The Project ID is not the same as the ODK Form ID. The Project ID identifies the ODK Central project, while the Form ID identifies a specific form within that project.

The email address or password is not working

Confirm that the same credentials can be used to sign in directly to ODK Central.

Check that:

  • The email address is correct
  • The password is correct
  • The account is active
  • The account has access to the required project

If the ODK Central password has changed, update the connection details in FieldOps.

Warning

Never include your ODK Central password in screenshots, support messages, or public documentation.

Test Connection fails

If Test Connection reports that the connection was unsuccessful, review:

  • Base URL
  • Project ID
  • Email address
  • Password
  • Access to the specified ODK Central project

Correct any incorrect information and select Test Connection again.

Do not create the connection until the connection test is successful.

Form mapping problems

The ODK Connection is not available

An ODK Central connection must be created before you can create an ODK Form Mapping.

Confirm that:

  • The connection was created successfully
  • The connection belongs to your active FieldOps organization
  • You have permission to access the connection

Create an ODK Central connection

The ODK Form ID is not working

The ODK Form ID is the technical identifier of the form.

It may be different from the visible form name.

For example:

  • Form Name: Monthly Site Monitoring
  • Form ID: monthly_site_monitoring

Copy the Form ID exactly as it appears in ODK Central.

Check that:

  • You copied the correct Form ID
  • You did not enter the Project ID
  • You did not enter the complete form URL
  • There are no extra spaces
  • The capitalization is correct
  • The form belongs to the ODK Central project configured in the selected connection

Important

The ODK Project ID and ODK Form ID are different values.

For example:

  • Project ID: 1
  • Form ID: monthly_site_monitoring

The form belongs to a different ODK Central project

An ODK Connection in FieldOps is associated with a specific ODK Central Project ID.

If the form belongs to another ODK Central project, the existing connection cannot be used for that form.

Create another ODK Connection using the Project ID of the project containing the form.

Then create the ODK Form Mapping using the new connection.

The Programme is not available

Confirm that:

  • The required Programme already exists in FieldOps
  • You are working in the correct FieldOps organization
  • You have access to the Programme

Create the required Programme before completing the form mapping if necessary.

The Project is not available

Confirm that:

  • The required FieldOps Project already exists
  • The Project belongs to the appropriate Programme
  • You are working in the correct FieldOps organization

Note

The FieldOps Project is different from the ODK Central Project.

The ODK Central Project ID identifies where the form is stored in ODK Central. The FieldOps Project determines where synchronized data is organized inside FieldOps.

The Site is not available

Confirm that:

  • The required Site already exists in FieldOps
  • You are working in the correct FieldOps organization
  • The Site is available for the mapping you are creating

No Monitoring Template is available

Selecting a Monitoring Template is optional.

If you do not have a suitable existing Monitoring Template, leave the field empty and continue creating the form mapping.

Synchronization problems

New submissions are not appearing immediately

FieldOps automatically synchronizes mapped ODK Central forms at regular intervals, typically about every 10 minutes.

A new submission may therefore take several minutes to appear in FieldOps.

If you want to synchronize immediately, use the Sync Now action on the ODK Form Mapping.

Tip

After creating a new form mapping, use Sync Now to test the integration without waiting for the next automatic synchronization cycle.

Sync Now does not retrieve any submissions

Check that:

  • The correct ODK Connection is selected
  • The ODK Project ID configured in the connection is correct
  • The ODK Form ID is correct
  • The connected ODK Central account has access to the project and form
  • The form contains submissions
  • The connection credentials are still valid
  • The form mapping has been created successfully

Also confirm that you are checking the correct FieldOps Programme, Project, and Site after synchronization.

Some submissions are missing

First confirm that the missing submissions exist in ODK Central.

Then:

  1. Wait for the next automatic synchronization cycle, or
  2. Use Sync Now to start synchronization immediately

If the submissions still do not appear, review:

  • The ODK Connection
  • The ODK Central Project ID
  • The ODK Form ID
  • The account's access to the project and form

Automatic synchronization appears delayed

Automatic synchronization runs in the background at regular intervals, typically about every 10 minutes.

The exact time before new data appears may vary depending on:

  • When the ODK submission was received
  • When the next synchronization cycle starts
  • The number of submissions being processed
  • Background processing and queue activity

If the data is needed immediately, use Sync Now.

Data appears under the wrong Programme, Project, or Site

The ODK Form Mapping determines the FieldOps context used for synchronized data.

Review the form mapping and confirm the selected:

  • Programme
  • Project
  • Site
  • Monitoring Template, if applicable

Warning

Review the mapping carefully before synchronizing a form. The selected Programme, Project, and Site determine where synchronized data belongs in FieldOps.

The connection previously worked but now fails

A previously working connection may stop working if:

  • The ODK Central password was changed
  • The ODK Central account was disabled
  • The account lost access to the project
  • The Project ID is incorrect
  • The ODK Central server is temporarily unavailable
  • The Base URL changed

Edit the connection details and use Test Connection to check the connection again.

Before contacting support

Before requesting assistance, collect the following information:

  • The name of the ODK Connection
  • The ODK Central Base URL
  • The ODK Central Project ID
  • The ODK Form ID
  • The Form Name
  • Whether the problem occurs during connection, mapping, or synchronization
  • The approximate time the problem occurred
  • Any error message displayed by FieldOps

Warning

Never include your ODK Central password when sharing troubleshooting information.

Screenshots can be helpful, but make sure they do not contain passwords or other sensitive credentials.

Connect ODK Central

Map an ODK Central form