Map an ODK Central Form¶

After creating an ODK Central connection, create a form mapping to tell FieldOps which ODK Central form to use and where data from that form belongs.

An ODK Form Mapping connects a specific form from the ODK Central project configured in the connection to the appropriate FieldOps operational context.

Before you begin¶

Make sure that:

An ODK Central connection has already been created and tested successfully
The ODK Central connection uses the correct Project ID
The connected ODK Central account has access to the form you want to map
You know the ODK Form ID
The required Programme exists in FieldOps
The required Project exists in FieldOps
The required Site exists in FieldOps

If you want to associate the form with an existing Monitoring Template, the template should also exist before creating the mapping.

Learn how to connect ODK Central

Step 1: Open ODK Form Mappings¶

Sign in to FieldOps and open ODK Form Mappings from the application navigation.

Select the action to create a new form mapping.

Step 2: Select the ODK Connection¶

Select the ODK Connection you created in the previous step.

The connection determines:

The ODK Central server FieldOps connects to
The ODK Central account used for authentication
The ODK Central Project ID containing the form

Note

If the connection you need is not available, create and test the ODK Central connection first.

Create an ODK Central connection

Step 3: Find the ODK Form ID¶

FieldOps requires the unique Form ID of the ODK Central form you want to synchronize.

The Form ID is the technical identifier assigned to the form. It may be different from the form's visible name.

For example:

Form name	Form ID
Monthly Site Monitoring	`monthly_site_monitoring`
Health Facility Assessment	`health_facility_assessment`

Find the Form ID in ODK Central¶

Sign in to your ODK Central server.
Open the Project you connected to FieldOps.
Open the form you want to map.
Open the form's Settings.
Look for the Form ID displayed in the form details.
Copy the Form ID exactly as shown.
Return to FieldOps and paste it into the ODK Form ID field.

For example, if ODK Central shows:

Form ID: monthly_site_monitoring

enter:

monthly_site_monitoring

into the ODK Form ID field in FieldOps.

Important

Copy the Form ID, not the visible form name. A form named Monthly Site Monitoring may have a Form ID such as monthly_site_monitoring.

Warning

Do not enter the ODK Central Project ID, the complete form URL, or the visible form name unless it is exactly the same as the Form ID.

If you cannot find the Form ID¶

The Form ID originates from the form's XForm definition and may also be referred to as the XML Form ID.

If you cannot find it in the form details:

Open the form in ODK Central.
Review the form's technical details or definition.
Look for the Form ID or XML Form ID.
Copy the value exactly as shown.

The value may look like:

monthly_site_monitoring

or another identifier chosen when the form was created.

Tip

Form IDs are case-sensitive. Copy the value exactly as it appears in ODK Central.

Step 4: Enter the Form Name¶

Enter a descriptive name for the ODK Central form in the Form Name field.

The Form Name is the human-readable name used to help users identify the form in FieldOps.

For example:

ODK Form ID: monthly_site_monitoring
Form Name: Monthly Site Monitoring

The Form ID tells FieldOps which ODK Central form to synchronize, while the Form Name provides a readable label for the mapping.

Step 5: Select the Programme¶

Select the FieldOps Programme that the ODK Central form belongs to.

The Programme provides the broader operational context for data synchronized from the form.

Step 6: Select the Project¶

Select the FieldOps Project associated with the ODK Central form.

Choose the Project under which synchronized data from this form should be organized.

Step 7: Select the Site¶

Select the FieldOps Site associated with the ODK Central form.

The Site identifies the operational or implementation location associated with data synchronized through this mapping.

Note

Choose the Programme, Project, and Site carefully. They determine the FieldOps context assigned to data synchronized from the mapped ODK Central form.

Step 8: Select a Monitoring Template, if applicable¶

The Monitoring Template is optional.

If you already have a Monitoring Template in FieldOps that represents the monitoring workflow associated with the ODK Central form, select it.

If no suitable Monitoring Template exists, leave the field empty.

Tip

You do not need to create a Monitoring Template solely to complete an ODK Form Mapping if your workflow does not require one.

Step 9: Create the form mapping¶

Before creating the mapping, review the selected information:

ODK Connection
ODK Form ID
Form Name
Programme
Project
Site
Monitoring Template, if selected

Select Create to save the form mapping.

Once the mapping has been created, FieldOps knows:

Which ODK Central connection to use
Which ODK Central project contains the form
Which ODK Central form to synchronize
Which Programme the data belongs to
Which Project the data belongs to
Which Site the data is associated with
Which Monitoring Template to use, if one was selected

How the mapping works¶

Conceptually, the mapping connects:

ODK Connection + ODK Form ID → Programme → Project → Site → Optional Monitoring Template

The ODK Connection identifies the ODK Central server and project, while the ODK Form ID identifies the specific form within that project.

The Programme, Project, Site, and optional Monitoring Template determine how synchronized data is organized in FieldOps.

Important

An ODK Form Mapping does not require you to manually map every individual ODK form question to a FieldOps monitoring field.

Step 10: Synchronize the ODK Central form¶

After creating the form mapping, FieldOps can synchronize submission data from the mapped ODK Central form.

You can synchronize the form in either of two ways.

Sync immediately¶

To synchronize the form immediately, find the ODK Form Mapping and select the Sync Now action.

FieldOps will start retrieving and processing available submissions from the mapped ODK Central form.

Use Sync Now when:

You have just created a new form mapping
You want to retrieve new submissions immediately
You do not want to wait for the next automatic synchronization

Automatic synchronization¶

You do not need to manually synchronize the form every time new submissions are added to ODK Central.

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

This means that new ODK Central submissions will normally become available in FieldOps automatically after the next synchronization cycle.

Note

Automatic synchronization runs in the background. Depending on when a submission was received in ODK Central, it may take several minutes before it appears in FieldOps.

After synchronization¶

FieldOps retrieves submissions from the mapped ODK Central form and processes them within the FieldOps context configured in the form mapping:

Programme
Project
Site
Monitoring Template, if selected

You can then work with the synchronized data in FieldOps according to the available visit, monitoring, review, findings, actions, and reporting workflows.

Tip

After creating a new form mapping, use Sync Now if you want to confirm the integration immediately. After that, you can rely on automatic synchronization for ongoing submissions.

Common problems¶

The ODK Connection is not available¶

Confirm that:

The ODK Central connection has already been created
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¶

Check that:

The Form ID is correct
You entered only the Form ID and not the complete URL
There are no extra spaces
The form belongs to the ODK Central project configured in the selected connection
The connected ODK Central account has access to the form

The form belongs to a different ODK Central project¶

The ODK Connection is associated with a specific ODK Central Project ID.

If the form belongs to another ODK Central project, create a separate ODK Connection using that project's Project ID.

Then create the form mapping using the new connection.

The Programme or Project is not available¶

Confirm that the required Programme and Project already exist in FieldOps.

Also make sure you are working in the correct FieldOps organization.

The Site is not available¶

Confirm that the required Site has already been created and is available in your FieldOps organization.

No Monitoring Template is available¶

A Monitoring Template is optional.

If you do not have an appropriate existing template, leave the field empty and continue creating the form mapping.

What to do next¶

After the first synchronization:

Confirm that the expected ODK Central submissions appear in FieldOps
Review the synchronized visit and response data
Continue using ODK Central for data collection
Allow FieldOps to synchronize new submissions automatically

If synchronization fails or expected submissions do not appear, review the troubleshooting guide.

Troubleshoot ODK Central

Review ODK connection setup