Skip to content

KoboToolbox 节点#

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

本页面列出了 KoboToolbox 节点支持的操作，并提供了更多资源的链接。

凭据

有关设置身份验证的指导，请参考 KoboToolbox 凭据。

操作#

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

模板和示例#

Browse KoboToolbox integration templates, or search all templates

选项#

查询选项#

Query Submission 操作支持以下查询选项：

  • 在 Parameters 面板的主区域：
    • Start 控制查询起始的索引偏移量（用于实现 API 分页逻辑）。
    • Limit 设置返回记录的最大数量。请注意无论您设置何值，API 始终限制返回 30,000 条记录。
  • 在 Query Options 区域，您可以启用以下参数：
    • Query 允许您以 MongoDB 的 JSON 查询格式指定过滤条件。例如：{"status": "success", "_submission_time": {"$lt": "2021-11-01T01:02:03"}} 表示查询所有 status 字段值为 success 且在 2021 年 11 月 1 日 01:02:03 之前提交的记录。
    • Fields 允许您指定需要获取的字段列表，以减轻响应负载。
    • Sort 允许您以 MongoDB JSON 格式提供排序条件列表。例如 {"status": 1, "_submission_time": -1} 表示按状态升序排列，再按提交时间降序排列。

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

提交选项#

所有返回表单提交数据的操作都提供调整响应的选项，包括：

  • 下载选项允许您下载与每个表单提交相关联的附件，如图片和视频。您还可以选择命名模式和要下载的文件大小（如果可用 - 通常针对图片）。
  • 格式化选项执行如 关于重新格式化 中描述的一些格式调整。

关于数据格式重构#

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

该节点提供了一个轻量级的、带有预设逻辑的格式重构功能，通过在所有返回表单提交的操作（包括提交查询、获取和附件下载操作）中提供的 Reformat? 参数启用。

启用后，格式重构会执行以下操作：

  • 将 JSON 按照表单的分组结构重新组织为多层级的层次结构。默认情况下，问题分组层次结构通过字段名中的 / 字符体现，例如 Group1/Question1。启用格式重构后，n8n 会将其重组为 Group1.Question1 形式的嵌套 JSON 对象。
  • 重命名字段以去除 _（许多下游系统不支持此符号）。
  • 将所有地理空间字段（点、线和面问题类型）解析为标准 GeoJSON 格式。
  • 将所有匹配 Multiselect Mask 通配符掩码的字段拆分为数组。由于多选字段以空格分隔的字符串形式出现，无法通过算法自动识别，因此必须提供字段命名掩码。掩码格式为逗号分隔的列表，支持 * 通配符。
  • 将所有匹配 Number Mask 通配符掩码的字段转换为 JSON 浮点数。

以下是 JSON 格式的详细示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "_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 会将其解析为：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
{
  "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
}

当操作不受支持时的解决方案#

如果当前节点不支持您想要执行的操作，可以使用 HTTP Request 节点 调用该服务的 API。

您可以在 HTTP Request 节点中使用为该服务创建的凭证：

  1. 在 HTTP Request 节点中，选择 Authentication > Predefined Credential Type。
  2. 选择您想要连接的服务。
  3. 选择您的凭证。

更多信息请参考 自定义 API 操作。