Map an ODK Central Form¶
After creating an ODK Central connection, create a form mapping to tell FieldOps which ODK Central form to synchronize and where the synchronized data 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 forms you want to map
- 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 containing the forms available for mapping
Note
If the connection you need is not available, create and test the ODK Central connection first.
Create an ODK Central connection
Step 3: Select the ODK Form¶
After selecting the ODK Connection, FieldOps automatically retrieves the forms available in the connected ODK Central project.
Select the ODK Form you want to synchronize.
You do not need to find or enter the ODK Form ID manually.
FieldOps uses the form information retrieved from ODK Central to identify the selected form when synchronizing submissions.
Available forms¶
The forms displayed for selection come from the ODK Central project configured in the selected connection.
For example, FieldOps may display:
| ODK Form |
|---|
| Monthly Site Monitoring |
| Health Facility Assessment |
| Community Follow-up |
Select the form that you want to connect to the FieldOps workflow.
Important
Select the correct form from the list. FieldOps automatically manages the form's technical identifier internally.
Note
The forms available for selection depend on the selected ODK Connection, the ODK Central Project configured for that connection, and the permissions of the connected ODK Central account.
Step 4: 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 5: 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 6: 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 7: 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 8: Create the form mapping¶
Before creating the mapping, review the selected information:
- ODK Connection
- ODK Form
- 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 selected 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 → Programme → Project → Site → Optional Monitoring Template
The ODK Connection identifies the ODK Central server and project.
FieldOps automatically retrieves the forms available in that project, allowing you to select the form you want to synchronize.
The Programme, Project, Site, and optional Monitoring Template determine how synchronized data is organized and processed in FieldOps.
Important
You do not need to manually find, copy, or enter the ODK Form ID. FieldOps retrieves and manages the form's technical identifier automatically.
Important
An ODK Form Mapping does not require you to manually map every individual ODK form question to a FieldOps monitoring field.
Step 9: 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 is not available¶
If the form you want to synchronize does not appear in the ODK Form selection, check the following:
- The selected ODK Central connection is working correctly
- The connection uses the correct ODK Central Project ID
- The form exists in the ODK Central project configured in the connection
- The connected ODK Central account has access to the form
- The form is available to the connected account
If the form is still not available, verify the ODK Central connection settings and try again.
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.