Map a KoboToolbox Form¶

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

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

Before you begin¶

Make sure that:

A KoboToolbox connection has already been created
You have access to the KoboToolbox form you want to map
You know the Kobo 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 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 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: Find the Kobo Form ID¶

FieldOps requires the unique identifier of the KoboToolbox form you want to map.

In KoboToolbox, this identifier is the form's asset UID. FieldOps refers to it as the Kobo Form ID.

Open the form or project in KoboToolbox and look at the URL in your browser.

The URL contains a unique identifier similar to:

ag8uJPUdTLrGSNdN5FHDKf

For example, if the URL contains:

/assets/ag8uJPUdTLrGSNdN5FHDKf/

the Kobo Form ID is:

ag8uJPUdTLrGSNdN5FHDKf

Copy only the unique identifier and enter it into the Kobo Form ID field in FieldOps.

Tip

The Kobo Form ID is usually a combination of letters and numbers. Copy it exactly as it appears in the KoboToolbox URL.

Warning

Do not enter the complete KoboToolbox URL into the Kobo Form ID field. Enter only the unique form identifier.

Step 4: Enter the Form Name¶

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

For example:

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

Use a name that makes the form easy to identify later in FieldOps.

Step 5: 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.

Step 6: Select the Project¶

Select the FieldOps Project associated with the KoboToolbox 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 KoboToolbox 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 KoboToolbox 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 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 9: Create the form mapping¶

Before creating the mapping, review the selected information:

Kobo Connection
Kobo 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 KoboToolbox connection to use
Which KoboToolbox 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:

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

The Kobo Form ID identifies the specific form on KoboToolbox, while the Programme, Project, Site, and optional Monitoring Template determine how its data is organized in FieldOps.

Important

A Kobo Form Mapping does not require you to manually map every individual KoboToolbox question to a FieldOps monitoring field.

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 Form ID is not working¶

Check that:

You copied the correct identifier from the KoboToolbox form URL
You copied only the form identifier, not the complete URL
There are no extra spaces before or after the ID
The selected Kobo Connection has access to the form
The KoboToolbox API token is still valid

A Kobo Form ID should look similar to:

ag8uJPUdTLrGSNdN5FHDKf

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.

Step 10: 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 start retrieving and processing available submissions from the mapped KoboToolbox 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 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, 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
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.

What to do next¶

After the first synchronization:

Confirm that the expected KoboToolbox submissions appear in FieldOps
Review the synchronized visit and response 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