Actions17
Overview
This node integrates with KoboToolbox to manage files associated with KoboToolbox forms. Specifically, the File - Create operation allows users to upload a file to a specified form in KoboToolbox. It supports multiple modes of uploading:
- Uploading binary data directly from incoming binary input.
- Uploading plain text content as a file.
- Uploading a file by providing a URL link.
This operation is useful when automating workflows that require adding media or other files to KoboToolbox forms, such as uploading images, documents, or datasets collected externally before submission processing.
Practical examples:
- Automatically upload photos collected from another system into a KoboToolbox form for later analysis.
- Add CSV or XML data files generated dynamically during a workflow to a form.
- Link external files hosted on a public URL to a form without downloading them first.
Properties
| Name | Meaning |
|---|---|
| Form Name or ID | The unique identifier of the KoboToolbox form where the file will be uploaded. Can be selected from a list or provided via expression. |
| File Upload Mode | Method of uploading the file. Options: Binary Data (upload from binary input), Plain Text (upload raw text content), URL (upload by linking an external file URL). |
| Property Name | (Shown if File Upload Mode is Binary Data) The name of the binary property in the input data containing the file to upload. Supported types include image, audio, video, csv, xml, zip. |
| File Content | (Shown if File Upload Mode is Plain Text) The raw text content of the file to upload. |
| File Name | (Shown if File Upload Mode is Plain Text) The filename to assign to the uploaded file (e.g., "myFile.jpg"). |
| Mime Type | (Shown if File Upload Mode is Plain Text) The MIME type to set for the uploaded file (default is "text/plain"). |
| File URL | (Shown if File Upload Mode is URL) The HTTP(s) link to the file to upload. |
| Overwrite Existing File with Same Name? | Whether to delete any existing file with the same name before uploading the new file. If enabled, the node will search for and remove the existing file to avoid duplicates. |
Output
The output JSON contains information about the uploaded file as returned by the KoboToolbox API. This typically includes metadata such as the file's unique ID, filename, description, and other attributes related to the uploaded file.
If the node downloads files (not applicable here for create operation), it can also output binary data representing the file content. For the create operation, the output is purely JSON describing the newly created file resource.
Dependencies
- Requires an active connection to KoboToolbox via an API key credential configured in n8n.
- Uses the KoboToolbox REST API endpoints for file management.
- The node depends on helper functions to handle base64 encoding of binary or text data and to interact with the API.
Troubleshooting
- No file found matching name: When overwriting or referencing files by name, if the file does not exist, the node throws an error. Ensure the filename is correct or exists in the target form.
- Invalid binary property: If using binary upload mode, ensure the specified binary property exists in the input data and contains supported file types.
- API errors: Errors from the KoboToolbox API (e.g., authentication failure, permission denied) will propagate. Verify API credentials and permissions.
- Missing required parameters: The form ID and file upload mode are mandatory. Missing these will cause the node to fail.
Links and References
- KoboToolbox API Documentation
- n8n Expressions Documentation (for dynamic parameter values)
- Base64 Encoding Explanation