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.

凭证

请参阅 KoboToolbox 凭证获取有关设置身份验证的指南。

操作(Operations)#

文件
- 创建
- 删除
- 获取
- 获取多个
表单
- 获取
- 获取多个
  - 重新部署
钩子
- 获取
- 获取多个
- 日志
- 全部重试
- 单次重试
提交
- 删除
- 获取
- 获取多个
- 获取验证状态
- 更新验证状态

模板和示例(Templates and examples)#

选项(Options)#

查询选项(Query Options)#

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

🌐 The Query Submission operation supports query options:

在参数面板的主要部分：
- Start 控制查询开始的索引偏移量（用于 API 分页逻辑）。
- Limit 设置要返回的最大记录数。请注意，无论你提供什么值，API 返回的记录数始终有 30,000 的限制。
在 查询选项 部分，你可以启用以下参数：
- Query 允许你以 MongoDB 的 JSON 查询格式指定过滤条件。例如：{"status": "success", "_submission_time": {"$lt": "2021-11-01T01:02:03"}} 查询在 status 字段的值为 success 并且提交时间在 2021 年 11 月 1 日 01:02:03 之前的所有提交。
- 字段让你指定想要获取的字段列表，以使响应更精简。
- Sort 允许你以 MongoDB JSON 格式提供排序标准列表。例如，{"status": 1, "_submission_time": -1} 指定先按状态升序排序，然后按提交时间降序排序。

有关这些选项的更多详细信息，请参阅 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:

下载选项允许你下载与每个特定表单提交相关的任何附件，例如图片和视频。它还允许你选择命名模式以及要下载的文件大小（如果可用——通常用于图片）。
格式化选项会执行一些重新格式化，如关于重新格式化中所述。

关于重新格式化(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.

该节点提供了一个轻量级的、有明确设计理念的重格式化逻辑，可通过 Reformat? 参数启用，适用于所有返回表单提交的操作：提交查询、获取操作以及附件下载操作。

🌐 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 对象。
重命名字段以去掉 _（许多下游系统不支持）。
将所有地理空间字段（点、线和面类型）解析为其标准的 GeoJSON 等效值。
将所有与任意 多选掩码 通配符匹配的字段拆分为数组。由于多选字段以空格分隔的字符串形式出现，无法通过算法猜测，因此必须提供字段命名掩码。将掩码格式为逗号分隔的列表。列表支持 * 通配符。
将所有匹配任意 数字掩码 通配符的字段转换为 JSON 浮点数。

以下是一个详细的 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.