Overview
This node acts as a trigger for new submissions on KoboToolbox forms. It listens for incoming form submission data via a webhook and processes it to be used in an n8n workflow. The node is useful when you want to automate workflows based on responses collected through KoboToolbox, such as sending notifications, updating databases, or triggering other integrations whenever a form is submitted.
Common scenarios include:
- Automatically processing survey results as soon as they are submitted.
- Downloading and handling file attachments submitted with the form.
- Reformatting submission data for easier downstream processing (e.g., parsing coordinates or converting certain fields).
Example: When a user submits a field survey form on KoboToolbox, this node triggers the workflow, optionally downloads any attached files, reformats the data, and passes it along for further automation like storing in a database or sending alerts.
Properties
| Name | Meaning |
|---|---|
| Form Name or ID | Select the KoboToolbox form by name or ID from a dropdown list or specify it dynamically using an expression. This identifies which form's submissions will trigger the node. |
| Trigger On | Defines the event that triggers the node. Currently only "On Form Submission" is supported, meaning the node activates when a new form submission occurs. |
| Options | A collection of additional options to customize how submission data is processed: |
| - Download Attachments | Whether to download any files attached to the submission. If enabled, attachments are fetched and added as binary data to the output. |
| - 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 binary properties when using the sequential naming scheme. For example, "attachment_" results in names like "attachment_0". |
| - File Size | Specifies which size/version of the attachment to download if multiple versions exist (Original, Small, Medium, Large). |
| - Multiselect Mask | Comma-separated wildcard selectors for fields that should be treated as arrays (multiselect fields). |
| - Number Mask | Comma-separated wildcard selectors for fields that should be parsed as numbers. |
| - Reformat | Whether to apply reformatting to the submission data, such as parsing GeoJSON coordinates or adjusting field formats for easier use downstream. |
Output
The node outputs JSON data representing the form submission:
- If Download Attachments is disabled, the output JSON contains the submission data as received (optionally reformatted).
- If Download Attachments is enabled, the node downloads the attachments and adds them as binary properties to the output. The binary property names follow the selected naming scheme and prefix.
- The output structure includes all form fields, with special handling for multiselect and numeric fields if configured.
- Binary data fields contain the actual file content of attachments, ready for further processing or saving.
Dependencies
- Requires an active connection to KoboToolbox via an API key credential configured in n8n.
- Needs internet access to receive webhook calls from KoboToolbox and to download attachments.
- Uses internal helper functions to interact with the KoboToolbox API and process submission data.
Troubleshooting
- Webhook not triggering: Ensure the webhook URL is correctly registered in KoboToolbox for the selected form. Use the node’s webhook management methods to verify or recreate the webhook.
- Attachments not downloading: Check that the "Download Attachments" option is enabled and that the form submissions actually include attachments. Also verify network connectivity.
- Incorrect field parsing: Adjust the "Multiselect Mask" and "Number Mask" settings to match your form’s field naming conventions so that fields are parsed correctly.
- Reformatting issues: If enabling reformat causes errors, verify that the submission data matches expected formats (e.g., valid GeoJSON) or disable reformatting.
- API errors: Make sure the API key credential has sufficient permissions and is valid.