Actions17
Overview
This node interacts with the KoboToolbox platform to manage files associated with KoboToolbox forms. Specifically, the File - Get operation retrieves metadata about a file linked to a specified form. It allows users to select the file either by its unique ID or by its filename. Additionally, it can optionally download the actual file content and store it in a binary property for further use within an n8n workflow.
Common scenarios where this node is beneficial:
- Automating retrieval of media or document files uploaded to KoboToolbox forms.
- Downloading files for processing, analysis, or storage in other systems.
- Integrating KoboToolbox file assets into broader data workflows without manual intervention.
Practical example:
A humanitarian organization collects survey data via KoboToolbox, including photos submitted by field workers. Using this node, they can automatically fetch specific photos by name or ID from a form and download them into their workflow for image processing or archival.
Properties
| Name | Meaning |
|---|---|
| Form Name or ID | The identifier of the KoboToolbox form containing the file. You can select from a list of available forms or specify the form ID directly (e.g., aSAvYreNzVEkrWg5Gdcvg). |
| Select File By | Choose how to identify the file to retrieve: by its unique ID (fileId) or by its filename (fileName). |
| File Name | The exact name of the file to retrieve (e.g., "myFile.jpg"). Required if selecting the file by name. |
| File ID | The unique identifier of the file (should start with "af", e.g., "afQoJxA4kmKEXVpkH6SYbhb"). Required if selecting the file by ID. |
| Download File Content | Boolean flag indicating whether to download the actual file content. If enabled, the file's binary data will be included in the output under a binary property. |
| Property Name | The name of the binary property where the downloaded file content will be stored. Defaults to "data". Only relevant if downloading the file content. |
Output
The node outputs JSON data representing the file's metadata retrieved from KoboToolbox. This includes details such as the file's unique ID, filename, metadata, and other attributes provided by the KoboToolbox API.
If the Download File Content option is enabled, the node also outputs the file's raw content in a binary property named as specified by the Property Name input. This binary data can be used downstream in the workflow for saving to disk, uploading elsewhere, or further processing.
The output structure when downloading content looks like:
{
"json": {
/* file metadata fields */
},
"binary": {
"<Property Name>": {
"data": "<base64 encoded file content>",
"mimeType": "<file MIME type>",
"fileName": "<original file name>"
}
}
}
If not downloading content, the output contains only the JSON metadata array.
Dependencies
- Requires a valid connection to the KoboToolbox API using an API key or token configured in n8n credentials.
- The node uses internal helper functions to make authenticated HTTP requests to KoboToolbox endpoints.
- No additional external services are required beyond access to the KoboToolbox API.
Troubleshooting
Error: "No file found matching name ..."
Occurs if the file cannot be located by the given filename. Ensure the filename is correct and exists in the specified form. Alternatively, try selecting the file by ID.Error related to missing file ID when selecting by name
The node attempts to resolve the file ID from the filename before fetching. If this fails, verify that the form contains the file and that the filename matches exactly.API authentication errors
Confirm that the API credentials are correctly set up in n8n and have sufficient permissions to access form files.Downloading large files may cause performance issues
When enabling file content download, large files might slow down execution or consume significant memory. Consider filtering or limiting file sizes.