KoboToolbox 2 icon

KoboToolbox 2

Work with KoboToolbox forms and submissions

Actions17

Overview

The node interacts with KoboToolbox, a platform for data collection via forms. Specifically, the "Submission" resource with the "Get Many" operation retrieves multiple form submissions from a specified form.

This node is useful when you want to:

  • Extract collected data submissions from a KoboToolbox form for further processing or analysis.
  • Apply filters and sorting to retrieve only relevant submissions.
  • Download attachments submitted with the forms.
  • Reformat submission data for easier consumption (e.g., parsing coordinates or handling multiselect fields).

Practical examples:

  • Export all survey responses submitted in the last month for reporting.
  • Retrieve submissions with specific criteria, such as those before a certain date or matching custom filters.
  • Automatically download photos or files attached to submissions for archival or processing.

Properties

Name Meaning
Form Name or ID The identifier of the form whose submissions are to be retrieved. Choose from a list or specify an ID directly.
Return All Whether to return all available submissions or limit the number of results.
Limit Maximum number of submissions to return if not returning all.
Filter Type of filter to apply on submissions. Options: None or JSON.
Filters (JSON) JSON string representing MongoDB-style query filters to narrow down submissions (only shown if Filter = JSON).
Options Collection of additional options:
- Download Attachments Whether to download any attachments included in the submissions.
- Attachments Naming Scheme How to name downloaded attachments: either sequentially (attachment_0, attachment_1, ...) or using the original form question IDs.
- Attachments Prefix Prefix for naming binary properties holding attachments when using sequential naming.
- Fields to Retrieve Comma-separated list of specific submission fields to retrieve. If empty, all fields are returned.
- File Size When downloading attachments, which size/version to retrieve (Original, Small, Medium, Large).
- Multiselect Mask Wildcard selectors for fields that should be parsed as arrays (multiselect fields).
- Number Mask Wildcard selectors for fields that should be treated as numbers.
- Reformat Whether to apply reformatting to submission data, e.g., parsing GeoJSON coordinates.
- Sort JSON object specifying sort order of results in MongoDB format (e.g., {"_submission_time":1} for ascending by submission time).

Output

  • The main output is a JSON array where each element represents a single submission record.
  • Each submission includes the requested fields, potentially reformatted according to options.
  • If attachments are downloaded, they are added as binary data properties to the output items. The naming of these binary properties depends on the chosen naming scheme and prefix.
  • Binary data contains the actual file content of attachments submitted with the form.

Dependencies

  • Requires an API key credential for authenticating with the KoboToolbox API.
  • Relies on the KoboToolbox REST API endpoints to fetch forms, submissions, and attachments.
  • Uses internal helper functions for formatting submissions and downloading attachments.
  • No additional external services beyond KoboToolbox are required.

Troubleshooting

  • No submissions returned: Check that the correct Form ID is provided and that there are submissions available. Also verify filter syntax if using JSON filters.
  • Attachments not downloaded: Ensure the "Download Attachments" option is enabled. Also check that the form submissions actually contain attachments.
  • Invalid filter JSON: The filter must be valid MongoDB JSON format. Refer to the linked Formhub API docs for correct syntax.
  • API authentication errors: Verify that the API key credential is correctly configured and has sufficient permissions.
  • Limit vs Return All confusion: If "Return All" is false but limit is very high, fewer results may be returned than expected. Set "Return All" to true to get all submissions.
  • Binary property naming conflicts: When downloading attachments, ensure the prefix and naming scheme do not conflict with existing properties.

Links and References

Discussion