KoboToolbox 节点#

¥KoboToolbox node

使用 KoboToolbox 节点可自动化 KoboToolbox 中的工作，并将 KoboToolbox 与其他应用集成。n8n 内置支持 KoboToolbox 的多种功能，包括创建、更新、删除和获取文件、表单、钩子和提交内容。

¥Use the KoboToolbox node to automate work in KoboToolbox, and integrate KoboToolbox with other applications. n8n has built-in support for a wide range of KoboToolbox features, including creating, updating, deleting, and getting files, forms, hooks, and submissions.

本页列出了 KoboToolbox 节点支持的操作列表以及更多资源的链接。

¥On this page, you'll find a list of operations the KoboToolbox node supports and links to more resources.

Credentials

请参阅 KoboToolbox 凭据以了解有关设置身份验证的指导。

¥Refer to KoboToolbox credentials for guidance on setting up authentication.

操作#

¥Operations

文件

¥File

创建

¥Create
删除

¥Delete
获取

¥Get
获取多个

¥Get Many
表单

¥Form

获取

¥Get
获取多个

¥Get Many
- 重新部署
¥Redeploy
钩子

¥Hook

获取

¥Get
获取多个

¥Get Many
日志

¥Logs
全部重试

¥Retry All
单次重试

¥Retry One
提交

¥Submission

删除

¥Delete
获取

¥Get
获取多个

¥Get Many
获取验证状态

¥Get Validation Status
更新验证状态

¥Update Validation Status

模板和示例#

¥Templates and examples

选项#

¥Options

查询选项#

¥Query Options

“查询提交”操作支持以下查询选项：

¥The Query Submission operation supports query options:

在“参数”面板的主部分：

¥In the main section of the Parameters panel:

“开始”控制查询的起始索引偏移量（以使用 API 分页逻辑）。

¥Start controls the index offset to start the query from (to use the API pagination logic).
限制设置要返回的最大记录数。请注意，无论你提供的值是多少，API 返回的记录数始终限制为 30,000 条。

¥Limit sets the maximum number of records to return. Note that the API always has a limit of 30,000 returned records, whatever value you provide.
在“查询选项”部分，你可以激活以下参数：

¥In the Query Options section, you can activate the following parameters:

查询允许你以 MongoDB 的 JSON 查询格式指定过滤谓词。例如：{"status": "success", "_submission_time": {"$lt": "2021-11-01T01:02:03"}} 查询所有字段 status 的值为 success，且提交时间在 2021 年 11 月 1 日 01:02:03 之前提交的记录。

¥Query lets you specify filter predicates in MongoDB's JSON query format. For example: {"status": "success", "_submission_time": {"$lt": "2021-11-01T01:02:03"}} queries for all submissions with the value success for the field status, and submitted before November 1st, 2021, 01:02:03.
字段允许你指定要获取的字段列表，以减轻响应的重量。

¥Fields lets you specify the list of fields you want to fetch, to make the response lighter.
排序功能允许你以 MongoDB JSON 格式提供排序条件列表。例如，{"status": 1, "_submission_time": -1} 指定按状态升序排序，然后按提交时间降序排序。

¥Sort lets you provide a list of sorting criteria in MongoDB JSON format. For example, {"status": 1, "_submission_time": -1} specifies a sort order by ascending status, and then descending submission time.

有关这些选项的更多详细信息，请参阅 Formhub API 文档。

¥More details about these options can be found in the Formhub API docs

提交选项#

¥Submission options

所有返回表单提交数据的操作均提供调整响应的选项。其中包括：

¥All operations that return form submission data offer options to tweak the response. These include:

下载选项允许你下载与每个特定表单提交关联的任何附件，例如图片和视频。它还允许你选择命名规则和下载文件大小（如果可用 - 通常针对图片）。

¥Download options lets you download any attachment linked to each particular form submissions, such as pictures and videos. It also lets you select the naming pattern, and the file size to download (if available - typically for images).

格式化选项会执行一些重新格式化操作，如关于重新格式化中所述。

¥Formatting options perform some reformatting as described in About reformatting.

关于重新格式化#

¥About reformatting

KoboToolbox 提交数据的默认 JSON 格式有时难以处理，因为它不具备模式感知能力，因此所有字段都以字符串形式返回。

¥The default JSON format for KoboToolbox submission data is sometimes hard to deal with, because it's not schema-aware, and all fields are therefore returned as strings.

此节点提供了一个轻量级的、预设的重新格式化逻辑，可通过“重新格式化？”启用。所有返回表单提交的操作均可使用此参数：提交查询、获取和附件下载操作。

¥This node provides a lightweight opinionated reformatting logic, enabled with the Reformat? parameter, available on all operations that return form submissions: the submission query, get, and the attachment download operations.

启用后重新格式化：

¥When enabled, the reformatting:

根据表单分组，将 JSON 重新组织成多级层次结构。默认情况下，问题分组层次结构通过字段名称中的 / 字符来体现，例如 Group1/Question1。启用重新格式化后，n8n 会将这些数据重新组织为 Group1.Question1，即嵌套的 JSON 对象。

¥Reorganizes the JSON into a multi-level hierarchy following the form's groups. By default, question grouping hierarchy is materialized by a / character in the field names, for example Group1/Question1. With reformatting enabled, n8n reorganizes these into Group1.Question1, as nested JSON objects.

重命名字段以去除 _（许多下游系统不支持此功能）。

¥Renames fields to trim _ (not supported by many downstream systems).

将所有地理空间字段（点、线和面类型）解析为其标准的 GeoJSON 等效值。

¥Parses all geospatial fields (Point, Line, and Area question types) into their standard GeoJSON equivalent.

将所有匹配多选掩码通配符的字段拆分为一个数组。由于多选字段显示为空格分隔的字符串，无法通过算法进行猜测，因此你必须提供字段命名掩码。将掩码格式化为逗号分隔的列表。列表支持 * 通配符。

¥Splits all fields matching any of the Multiselect Mask wildcard masks into an array. Since the multi-select fields appear as space-separated strings, they can't be guessed algorithmically, so you must provide a field naming mask. Format the masks as a comma-separated list. Lists support the * wildcard.

将所有匹配任何数字掩码通配符的字段转换为 JSON 浮点数

¥Converts all fields matching any of the Number Mask wildcard masks into a JSON float.

以下是一个详细的 JSON 示例：

¥Here's a detailed example in JSON:

{
  "_id": 471987,
  "formhub/uuid": "189436bb09a54957bfcc798e338b54d6",
  "start": "2021-12-05T16:13:38.527+02:00",
  "end": "2021-12-05T16:15:33.407+02:00",
  "Field_Details/Field_Name": "Test Fields",
  "Field_Details/Field_Location": "-1.932914 30.078211 1421 165",
  "Field_Details/Field_Shape": "-1.932914 30.078211 1421 165;-1.933011 30.078085 0 0;-1.933257 30.078004 0 0;-1.933338 30.078197 0 0;-1.933107 30.078299 0 0;-1.932914 30.078211 1421 165",
  "Field_Details/Crops_Grown": "maize beans avocado",
  "Field_Details/Field_Size_sqm": "2300",
  "__version__": "veGcULpqP6JNFKRJbbMvMs",
  "meta/instanceID": "uuid:2356cbbe-c1fd-414d-85c8-84f33e92618a",
  "_xform_id_string": "ajXVJpBkTD5tB4Nu9QXpgm",
  "_uuid": "2356cbbe-c1fd-414d-85c8-84f33e92618a",
  "_attachments": [],
  "_status": "submitted_via_web",
  "_geolocation": [
    -1.932914,
    30.078211
  ],
  "_submission_time": "2021-12-05T14:15:44",
  "_tags": [],
  "_notes": [],
  "_validation_status": {},
  "_submitted_by": null
}

启用重新格式化，并使用相应的多选和数字格式掩码（例如，分别为 Crops_* 和 *_sqm）后，n8n 会将其解析为：

¥With reformatting enabled, and the appropriate masks for multi-select and number formatting (for example, Crops_* and *_sqm respectively), n8n parses it into:

{
  "id": 471987,
  "formhub": {
    "uuid": "189436bb09a54957bfcc798e338b54d6"
  },
  "start": "2021-12-05T16:13:38.527+02:00",
  "end": "2021-12-05T16:15:33.407+02:00",
  "Field_Details": {
    "Field_Name": "Test Fields",
    "Field_Location": {
      "lat": -1.932914,
      "lon": 30.078211
    },
    "Field_Shape": {
      "type": "polygon",
      "coordinates": [
        {
          "lat": -1.932914,
          "lon": 30.078211
        },
        {
          "lat": -1.933011,
          "lon": 30.078085
        },
        {
          "lat": -1.933257,
          "lon": 30.078004
        },
        {
          "lat": -1.933338,
          "lon": 30.078197
        },
        {
          "lat": -1.933107,
          "lon": 30.078299
        },
        {
          "lat": -1.932914,
          "lon": 30.078211
        }
      ]
    },
    "Crops_Grown": [
      "maize",
      "beans",
      "avocado"
    ],
    "Field_Size_sqm": 2300
  },
  "version": "veGcULpqP6JNFKRJbbMvMs",
  "meta": {
    "instanceID": "uuid:2356cbbe-c1fd-414d-85c8-84f33e92618a"
  },
  "xform_id_string": "ajXVJpBkTD5tB4Nu9QXpgm",
  "uuid": "2356cbbe-c1fd-414d-85c8-84f33e92618a",
  "attachments": [],
  "status": "submitted_via_web",
  "geolocation": {
    "lat": -1.932914,
    "lon": 30.078211
  },
  "submission_time": "2021-12-05T14:15:44",
  "tags": [],
  "notes": [],
  "validation_status": {},
  "submitted_by": null
}

What to do if your operation isn't supported#

If this node doesn't support the operation you want to do, you can use the HTTP Request node to call the service's API.

You can use the credential you created for this service in the HTTP Request node:

In the HTTP Request node, select Authentication > Predefined Credential Type.
Select the service you want to connect to.
Select your credential.

Refer to Custom API operations for more information.