KoboToolbox 2

Work with KoboToolbox forms and submissions

Actions17

Overview

This node interacts with KoboToolbox, a platform for data collection via forms. Specifically, the Submission - Get operation retrieves a single submission from a specified form by its submission ID. It allows fetching detailed data of one submission, optionally filtering which fields to retrieve, reformatting the data, and downloading any attachments submitted.

Common scenarios where this node is useful include:

Fetching individual survey or form responses for further processing or analysis.
Retrieving specific submission data to trigger workflows based on user input.
Downloading files attached to a particular submission for archival or processing.

For example, you might use this node to get a submission by its ID, extract certain fields like submission time and submitter info, and download any photos or documents attached to that submission.

Properties

Name	Meaning
Form Name or ID	The unique identifier or name of the form from which to retrieve the submission. You can select from a list or specify an ID using an expression.
Submission ID	The numeric ID of the submission to retrieve (e.g., 245128).
Options	A collection of optional settings:
Download Attachments	Whether to download any files attached to the submission. If enabled, attachments will be downloaded as binary data.
Attachments Naming Scheme	How to name the binary properties for downloaded attachments: either sequentially (attachment_0, attachment_1, ...) or using the original form question IDs.
Attachments Prefix	Prefix for naming the binary properties when using the sequential naming scheme (default "attachment_").
Fields to Retrieve	Comma-separated list of specific fields to fetch from the submission (e.g., _submission_time,_submitted_by). If left blank, all fields are retrieved.
File Size	When downloading attachments, choose the size/version to retrieve if multiple versions exist: Original, Small, Medium, or Large.
Multiselect Mask	Wildcard selectors for fields that should be parsed as arrays (multiselect fields), e.g., "select_*".
Number Mask	Wildcard selectors for fields that should be treated as numbers, e.g., "n_, f_".
Reformat	Whether to apply reformatting to the submission data, such as parsing GeoJSON coordinates into usable formats.
Sort	Sort predicates in MongoDB JSON format (not typically used for single submission retrieval).

Output

The node outputs JSON data representing the requested submission. The structure corresponds to the submission's fields and values as stored in KoboToolbox, optionally filtered by the selected fields.

If attachments are downloaded, they are included as binary properties on the output item. The binary property names follow the chosen naming scheme and prefix, each containing the file content and metadata such as filename.

Example output JSON snippet (simplified):

{
  "_submission_time": "2023-01-01T12:00:00Z",
  "_submitted_by": "[email protected]",
  "question_1": "Answer text",
  "question_2": ["option1", "option2"],
  // ... other fields ...
}

If attachments are downloaded, the output item will also have binary properties like:

{
  "binary": {
    "attachment_0": {
      "data": "<base64-encoded file content>",
      "mimeType": "image/jpeg",
      "fileName": "photo1.jpg"
    },
    "attachment_1": {
      "data": "<base64-encoded file content>",
      "mimeType": "application/pdf",
      "fileName": "document.pdf"
    }
  }
}

Dependencies

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

Troubleshooting

Missing or invalid Form ID: Ensure the form ID is correct and accessible with your API credentials. Use the provided load options to select valid forms.
Submission not found: Verify the submission ID exists for the given form. The node will throw an error if the submission does not exist.
Attachment download failures: Check network connectivity and permissions. Also verify that the submission actually contains attachments if download is enabled.
Field filtering issues: If specifying fields, ensure field names are correct and comma-separated without extra spaces.
Reformat option unexpected results: The reformatting applies heuristics like parsing GeoJSON; if data looks incorrect, try disabling this option.

Common error messages usually relate to HTTP errors from the API (404 Not Found, 401 Unauthorized) or invalid parameters. Resolving these involves checking credentials, form/submission IDs, and network access.