Map a KoboToolbox Form¶

After creating a KoboToolbox connection, create a form mapping to tell FieldOps which KoboToolbox form to synchronize and where the synchronized data belongs.

A Kobo Form Mapping connects a specific KoboToolbox form to the appropriate FieldOps operational context.

FieldOps automatically retrieves the forms available through the selected KoboToolbox connection, so you do not need to manually copy and enter the Kobo Form ID.

Before you begin¶

Make sure that:

A KoboToolbox connection has already been created
You have access to the KoboToolbox form 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 assign a default site
You know which Monitoring Template to use, if applicable

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 KoboToolbox

Step 1: Open Kobo Form Mappings¶

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

Select the action to create a new form mapping.

Step 2: Select the Kobo Connection¶

Select the Kobo Connection you created when connecting FieldOps to your KoboToolbox account.

The connection determines:

The KoboToolbox server FieldOps connects to
The KoboToolbox account used to access the forms and submission data
The API credentials used for synchronization

Note

If the connection you need is not available, create the KoboToolbox connection first.

Create a KoboToolbox connection

Step 3: Select the Kobo Form¶

After selecting a Kobo Connection, FieldOps automatically retrieves the KoboToolbox forms that are accessible through that connection.

The Kobo Form field becomes available once the forms have been loaded.

You can search the list to quickly find the form you want to map.

For example, you may see forms such as:

Monthly School Monitoring
Health Facility Assessment
Partner Monitoring Visit
Project Site Inspection

Select the KoboToolbox form you want FieldOps to synchronize.

Tip

You do not need to copy the Kobo Form ID from the KoboToolbox URL. FieldOps retrieves the available forms automatically and uses the selected form's unique identifier internally.

Note

The forms displayed depend on the KoboToolbox connection you selected and the forms that account is authorized to access.

Loading Kobo forms¶

When you select a Kobo Connection, FieldOps may briefly display Loading Kobo forms... while it retrieves the available forms from KoboToolbox.

Wait for the forms to finish loading before selecting a Kobo Form.

Warning

Do not change or submit the mapping while the Kobo forms are still loading.

No forms are available¶

If no forms are returned for the selected connection, check that:

The KoboToolbox connection is configured correctly
The KoboToolbox account has access to the expected form
The form exists in the selected KoboToolbox server
The KoboToolbox API credentials are still valid

Step 4: Select the Programme¶

Select the FieldOps Programme that the KoboToolbox form belongs to.

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

Note

Only Programmes available to your active FieldOps organization are available for selection.

Step 5: Select the Project¶

Select the FieldOps Project associated with the KoboToolbox form.

The available Projects are filtered according to the selected Programme.

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

Note

Select the Programme first. The Project selector depends on the selected Programme.

Step 6: Select the Site¶

Select the FieldOps Site associated with the KoboToolbox form, if applicable.

The available Sites are filtered according to the selected Project.

The Site is optional and can be used as the default site for submissions synchronized through this mapping.

Note

A Site is optional. Leave it empty if the site should be determined through your synchronization or mapping workflow rather than assigned as a default.

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 KoboToolbox 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 a Kobo Form Mapping if your workflow does not require one.

Step 8: Configure Field Mapping, if required¶

The Field Mapping (JSON) section is an advanced configuration area for defining how KoboToolbox fields should correspond to FieldOps fields.

For most standard mappings, you should only modify this section if your FieldOps implementation requires custom field mapping.

Warning

Only modify the Field Mapping JSON if you understand the expected mapping structure. Invalid JSON or incorrect field mappings can prevent synchronized data from being processed correctly.

Step 9: Configure Site Mapping Rules, if required¶

The Site Mapping Rule section allows you to define rules for determining the FieldOps Site from information contained in KoboToolbox submissions.

This is useful when a single KoboToolbox form is used to collect data for multiple FieldOps Sites.

If you have selected a default Site and do not require submission-based site matching, you can leave this field empty.

Step 10: Set the mapping status¶

The Active setting determines whether the mapping is active.

An active mapping can participate in synchronization.

Leave the mapping active if you want FieldOps to continue synchronizing submissions from the selected KoboToolbox form.

Step 11: Create the form mapping¶

Before creating the mapping, review the selected information:

Kobo Connection
Kobo Form
Programme
Project
Site, if applicable
Monitoring Template, if applicable
Field Mapping, if applicable
Site Mapping Rules, if applicable
Active status

Select Create to save the form mapping.

Once the mapping has been created, FieldOps knows:

Which KoboToolbox connection to use
Which KoboToolbox form to synchronize
Which Programme the data belongs to
Which Project the data belongs to
Which Site should be used as the default, if selected
Which Monitoring Template to use, if one was selected
Any custom field or site mapping rules configured for the mapping

How the mapping works¶

Conceptually, the mapping connects:

Kobo Connection + Kobo Form → Programme → Project → Optional Site → Optional Monitoring Template

Additional advanced configuration can be applied through:

Field Mapping + Site Mapping Rules

The Kobo Form is selected directly from the forms available through the Kobo Connection. FieldOps stores the form's unique identifier internally.

Important

You do not need to manually enter the Kobo Form ID or Kobo Form Name. FieldOps retrieves the form information directly from KoboToolbox when you select the Kobo Connection.

Important

A Kobo Form Mapping does not require you to manually map every individual KoboToolbox question to a FieldOps monitoring field. Advanced field mapping is available when your workflow requires it.

Editing an existing Kobo Form Mapping¶

You can edit an existing Kobo Form Mapping from the Kobo Form Mappings list.

When you open a mapping for editing, FieldOps automatically loads the forms available through the mapping's existing Kobo Connection.

The currently selected Kobo Form remains selected.

You can then change other mapping settings without having to manually enter the Kobo Form ID again.

Changing the Kobo Connection¶

If you change the Kobo Connection, FieldOps clears the currently selected Kobo Form and loads the forms available through the newly selected connection.

You must then select a Kobo Form from the newly loaded list.

Warning

A Kobo Form belongs to a specific KoboToolbox connection. If you change the connection, always select the appropriate form from the newly loaded list.

Common problems¶

The Kobo Connection is not available¶

Confirm that:

The KoboToolbox connection has already been created
The connection belongs to your active FieldOps organization
You have permission to access the connection

Create a KoboToolbox connection

The Kobo forms are still loading¶

After selecting a Kobo Connection, FieldOps retrieves the available forms from KoboToolbox.

If Loading Kobo forms... remains visible for an unusually long time:

Check your internet connection
Confirm that the KoboToolbox connection is valid
Confirm that the KoboToolbox server is accessible
Check that the KoboToolbox API credentials are still valid
Try selecting the connection again

No Kobo forms are available¶

If the Kobo Form selector does not contain the form you expect, check that:

The selected Kobo Connection is correct
The KoboToolbox account has access to the form
The form exists on the selected KoboToolbox server
The KoboToolbox API credentials are valid
The form has not been archived or deleted

Tip

If the form is accessible through KoboToolbox but does not appear in FieldOps, verify the Kobo Connection first. FieldOps only displays forms available through the selected connection.

I cannot find the Kobo Form¶

Use the search functionality in the Kobo Form selector.

Search by part of the form's name rather than trying to enter its Kobo Form ID manually.

For example, if the form is named:

Monthly School Monitoring - 2026

you can search for:

Monthly School

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.

Remember that Projects are filtered according to the selected Programme.

The Site is not available¶

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

Also confirm that the Site belongs to the selected Project.

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.

The mapping cannot be saved¶

Check that:

A Kobo Connection has been selected
A Kobo Form has been selected
A Programme has been selected
A Project has been selected
Any required advanced JSON configuration contains valid JSON
The selected Kobo Form is still available through the selected Kobo Connection

Synchronize the KoboToolbox form¶

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

You can synchronize the form in either of two ways.

Sync immediately¶

To synchronize the form immediately, find the form mapping and select the Sync Now action.

FieldOps will queue the synchronization process and retrieve available submissions from the mapped KoboToolbox form in the background.

Use Sync Now when:

You have just created a new form mapping
You want to retrieve new submissions immediately
You want to verify that the connection and mapping are working
You do not want to wait for the next automatic synchronization

Note

Sync Now queues the synchronization as a background job. The synchronization may continue after you leave the page.

Automatic synchronization¶

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

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

This means that new KoboToolbox 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 KoboToolbox and when the synchronization cycle runs, it may take several minutes before it appears in FieldOps.

After synchronization¶

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

Programme
Project
Site, if configured
Monitoring Template, if selected
Field Mapping, if configured
Site Mapping Rules, if configured

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.

What to do next¶

After the first synchronization:

Confirm that the expected KoboToolbox submissions appear in FieldOps
Review the synchronized visit and response data
Confirm that the Programme, Project, and Site context is correct
Review any Monitoring Template or field mappings applied to the synchronized data
Continue using KoboToolbox for data collection
Allow FieldOps to synchronize new submissions automatically

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

Troubleshoot KoboToolbox