camunda-connectors

Camunda 连接器

浏览并配置预构建的 Camunda 连接器，使用元素模板将连接器配置应用于 BPMN 服务任务和事件元素，以便与外部系统集成（REST API、Slack、Kafka、AWS、电子邮件、数据库等）。

先决条件

• 已安装并配置 c8ctl CLI（c8ctl add profile）——提供 c8ctl element-template 命令
• 已同步本地 OOTB 目录——在使用 OOTB 模板 ID 执行 search、info、get-properties、get 或 apply 之前，先运行一次 c8ctl element-template sync。如需获取上游更改，可重新运行（可选加上 --prune）。从本地文件路径或 https:// URL 应用模板会绕过缓存，无需同步。
• element-template update 需要 c8ctl ≥ 4.6.1。
• 发现命令的 --engine-version 和 --set 的 FEEL 自动添加 = 功能需要 c8ctl ≥ 3.2.0。如果命令或标志不可用，请让用户升级：npm install -g @camunda8/cli

交叉引用

• camunda-bpmn：用于创建 BPMN 流程结构（承载连接器的服务任务和事件元素）
• camunda-feel：用于连接器输入／输出映射中的 FEEL 表达式
• camunda-process-mgmt：用于将配置好的流程部署到集群

说明

元素模板

元素模板（也称为连接器模板——这两个术语在 Camunda 文档和工具中交替使用）是封装连接器配置的 JSON 文件。每个模板定义：

• 用于标识由哪个连接器运行时处理作业的任务类型
• 属性及其绑定，这些绑定映射到 BPMN XML（输入映射、任务标头等）
• 条件，用于根据用户选择控制哪些属性处于启用状态
• 约束，用于验证用户输入（必填字段、URL 模式等）
• 分组，用于将属性整理为逻辑部分（身份验证、端点、输出、错误处理）

请阅读 references/element-template-schema.md，了解属性字段及其到 BPMN XML 的绑定映射指南。完整的编写架构请参阅 camunda-connectors-development。

通过搜索发现连接器

始终使用 c8ctl element-template search 查找模板 ID，而不要猜测或凭记忆提供 ID。 模板 ID 和版本会不断演进，搜索命令会反映本地 OOTB 目录中实际可用的内容。

c8ctl element-template search "REST"                              # find HTTP/REST connectors
c8ctl element-template search "slack"                             # find Slack connectors
c8ctl element-template search "kafka"                             # find Kafka connectors
c8ctl element-template search "connector" --limit 5              # cap results (default 20)
c8ctl element-template search "REST" --engine-version 8.8.0      # latest version compatible with 8.8.0

每个结果都会显示模板名称、ID（例如 io.camunda.connectors.HttpJson.v2）、版本、appliesTo、引擎约束和说明。标题会显示 Showing N of M matches for '<query>'——如果 M > N，请缩小查询范围或增大 --limit。选择符合用例的 ID。

入站集成通常会以一组模板的形式提供——每种入站事件可附加到的 BPMN 元素类型各对应一个模板（消息开始事件、中间捕获事件、边界事件、接收任务等）。search 会返回各个变体；请选择与所建模的 BPMN 图形相匹配的模板。

检查模板

以下两个命令可解答应用模板前你会提出的问题：

• c8ctl element-template info <id> [--engine-version <x.y.z>] — 元数据卡片（适用范围、引擎约束、描述、文档链接）。传入 --engine-version 可解析与该引擎兼容的最新版本。连接器不熟悉时很有用。
• c8ctl element-template get-properties <id> [<name>...] [--engine-version <x.y.z>] — 可设置的属性（精简视图：名称 + 描述，按组排列）。支持位置名称（可使用 shell 风格的 glob，需加引号），也支持使用 --group <id> 缩小范围。传入 --engine-version 可解析与该引擎兼容的最新版本。添加 --detailed 可查看每个属性的卡片，其中显示 Required、FEEL、Active when、Pattern、Default、Choices — 在 apply --set 调用失败时，或需要确认值是否要加 = 前缀时，使用 --detailed。

c8ctl element-template get-properties io.camunda.connectors.HttpJson.v2 url method
c8ctl element-template get-properties io.camunda.connectors.HttpJson.v2 --group endpoint
c8ctl element-template get-properties io.camunda.connectors.HttpJson.v2 --detailed authentication.token

如果属性的内部 ID 与其绑定名称（--set 匹配的名称）不同，精简视图会在后续行将其标注为 [id: <internal>] — 使用 --set 时始终使用首行名称。

将模板应用于 BPMN 元素

将模板应用于服务任务（或其他受支持的元素）— 一次调用即可生成配置完整的连接器：

c8ctl element-template apply -i io.camunda.connectors.HttpJson.v2 Task_FetchUser process.bpmn

<template> 参数可以是：

• OOTB 模板 ID（可选 @<version>，例如 io.camunda.connectors.HttpJson.v2@13）。不带 @<version> 时，会自动解析与 BPMN 的 executionPlatformVersion 兼容的最高版本。要求至少运行过一次 c8ctl element-template sync。
• 本地文件路径（例如 ./my-custom-template.json）— 无需同步
• https:// URL（GitHub blob URL 会自动重写为 raw 内容）— 无需同步

-i 会就地修改 BPMN 文件。不使用 -i 时，修改后的 XML 会打印到 stdout — 适用于预览、重定向输出，或与其他工具组合使用：

c8ctl element-template apply <id> <element> process.bpmn | diff process.bpmn -    # preview the diff
c8ctl element-template apply <id> <element> process.bpmn > new-process.bpmn       # write to a different file
c8ctl element-template apply <id> <element> process.bpmn | c8ctl bpmn lint        # apply and lint in one pipeline

Apply 会将 zeebe:modelerTemplate、zeebe:modelerTemplateVersion、zeebe:modelerTemplateIcon、zeebe:taskDefinition、**整个 zeebe:ioMapping 块（输入和输出）**以及 zeebe:taskHeaders 写入该元素。所有这些内容必须保持一致 — 它们由 apply 管理。尤其是，手动添加到连接器元素的自定义 <zeebe:output> 映射会在下次 apply 时被清除 — 请将下游提取放在单独的活动中，或放在后续流程元素的 <zeebe:ioMapping> 中（结束事件也接受该映射）。

apply 会自动解析与 BPMN 的 executionPlatformVersion 兼容的最新 OOTB 模板版本。在 search、info 或 get-properties 中传入 --engine-version <x.y.z>，可在发现模板时应用相同的引擎兼容性筛选 — search 会返回每个模板的最新兼容版本，info / get-properties 会通过相同的检查进行解析。指定的 @<version>（例如 io.camunda.connectors.HttpJson.v2@12）始终优先于 --engine-version；两者不匹配时会发出警告。

在应用时设置属性值

在同一次 apply 调用中重复使用 --set key=value 标志来设置每个值：

c8ctl element-template apply -i io.camunda.connectors.HttpJson.v2 Task_FetchUser process.bpmn \
  --set method=GET \
  --set url='="https://api.example.com/users/" + string(userId)' \
  --set authentication.type=bearer \
  --set authentication.token='{{secrets.API_TOKEN}}' \
  --set resultExpression='={user: response.body}'

注意 string(userId) 包装器——userId 是数字，FEEL 不会在字符串拼接时自动转换类型。若不使用 string()，表达式会静默求值为 null（随后连接器会向 null 发起请求）。有关 FEEL 类型转换的详细信息，请参阅 camunda-feel。

key 与模板的属性绑定名称对应——使用 get-properties 查找。如果同一名称出现在多个绑定类型中，请在前面加上 input:、output:、header:、property: 或 taskDefinition:：

--set input:correlationKey='=order.id'
--set header:correlationKey=staticHeaderValue

如果传入未知属性，apply 会报错并列出有效名称；如果不带限定的键存在歧义，则会报错并列出限定名称。

FEEL 值语法。 feel: required 值必须以 = 开头。标准形式为 --set key='=value'；也可以使用 --set 'key==value'（紧凑形式）。对于 feel: required 属性，如果值不以 = 开头，c8ctl 会自动添加 =，因此 --set key=expression 会存储为 =expression；值侧的空白会被去除。不确定某个属性的 feel 设置时，请检查 get-properties --detailed <name>。

默认值会固化。 apply 会将每个启用且具有默认值的属性写入 BPMN，包括 <zeebe:input>、<zeebe:output>、<zeebe:taskHeaders> 和 <zeebe:property> 条目，而不仅仅是通过 --set 设置的键。默认值会在应用时写入——如果模板之后提供了新的默认值，此 BPMN 仍保留旧值。

重新应用。 未提供的 --set 键会保留当前 XML 值，因此重新应用单个属性不会影响其他属性。例外：每次重新应用时，下拉列表都会重置为模板默认值。

将元素更新到较新模板 — update (c8ctl 4.6.1+)

update 会将已关联模板的元素迁移到该模板的较新版本（也可通过 --to <id>[@<n>]、路径或 URL 迁移到其他模板），同时沿用现有值并报告每项变更。建议优先使用此命令，而不是在新目录版本上重新运行 apply——apply 会重置下拉列表。

c8ctl element-template update <template-id> process.bpmn --dry-run             # preview, writes nothing
c8ctl element-template update <template-id> [<element-id>] process.bpmn -i     # write: all matching elements, or one

• 选择。 <template-id> 是当前使用的模板；每条命令只能指定一个 ID。不指定元素 ID 时，会更新该模板下的所有元素（任意版本）；指定元素 ID 时，只更新该元素，且该元素必须使用 <template-id>。
• 目标。 默认选择与 BPMN 的 executionPlatformVersion 兼容的最新版本；请先运行 sync。
• 值。 同名键的值会沿用。如果目标模板将某个值绑定到另一个键，则只有通过目标模板中的迁移配方（metadata.migratesFrom）、--recipe <file> 或 --map <from>=<to> 才会迁移该值；其余值会在报告中列出。
• 报告。 标记包括：+ 新增、~ 已更改、> 已移动、- 已删除，以及配方说明。--json 会输出结构化形式；建议 Agent 使用此选项。
• 安全性。 只有在所有选定元素都成功迁移时，文件才会写入一次。如果有元素会迁移失败，或写入需要 --allow-lossy，--dry-run 会以状态码 1 退出——只有在查看了所有被删除的值之后才传入该选项。

此处尚未介绍每个连接器的迁移配方；有关 AI Agent v1 → v2 的迁移，请参阅 camunda-ai-agents。

结果映射 — resultVariable 和 resultExpression

连接器在 输出映射 组下提供两个属性，用于控制连接器完成时写回流程作用域的内容：

• resultVariable — 接收原始响应的单个流程变量的名称。纯字符串，不带 = 前缀。适用于下游任务只需通过一个名称获取完整响应的情况。
• resultExpression — 针对响应求值的 FEEL 表达式，其结果会合并到流程作用域中。必须带 = 前缀。适用于提取特定字段、重命名字段或计算派生值的情况。

两者可以同时设置——resultVariable 捕获原始响应，resultExpression 则在其旁写入经过整理的命名变量。如果两者均未设置，响应就会被丢弃，下游任务无法看到此连接器产生的新变量。

--set resultVariable=apiResponse \
--set resultExpression='={user: response.body.user, status: response.statusCode}'

同样的机制也适用于入站连接器——例如，Slack 入站连接器会在同一个输出映射组下提供 resultVariable 和 resultExpression。触发器触发时，引擎会将传入的事件负载写入流程作用域，与服务任务完成时出站连接器写入响应的方式相同。

将连接器用作 AI Agent 工具时，其输出必须通过 toolCallResult 变量提供（该概念请参见 camunda-ai-agents）。REST 连接器通常使用 resultExpression='={toolCallResult: response.body}'；其他连接器也使用相同的 resultExpression/resultVariable 机制，但会根据各自的响应进行调整。

示例 — HTTP REST 连接器

# 1. Discover the template
c8ctl element-template search "REST"
# → io.camunda.connectors.HttpJson.v2 (REST Outbound Connector)

# 2. Apply with all values in one call
c8ctl element-template apply -i io.camunda.connectors.HttpJson.v2 Task_FetchUser process.bpmn \
  --set authentication.type=bearer \
  --set authentication.token='{{secrets.API_TOKEN}}' \
  --set method=GET \
  --set url='="https://api.example.com/users/" + string(userId)' \
  --set resultVariable=apiResponse \
  --set resultExpression='={user: response.body}' \
  --set errorExpression='=if response.statusCode >= 400 then bpmnError("HTTP_ERROR", string(response.statusCode)) else null'

生成的 BPMN（为便于阅读，此处省略 data:image/svg+xml;base64,... 图标数据块——实际文件中请保留）：

<bpmn:serviceTask id="Task_FetchUser" name="Fetch user data"
  zeebe:modelerTemplate="io.camunda.connectors.HttpJson.v2"
  zeebe:modelerTemplateVersion="13"
  zeebe:modelerTemplateIcon="data:image/svg+xml;base64,...">
  <bpmn:extensionElements>
    <zeebe:taskDefinition type="io.camunda:http-json:1" retries="3" />
    <zeebe:ioMapping>
      <zeebe:input source="bearer" target="authentication.type" />
      <zeebe:input source="{{secrets.API_TOKEN}}" target="authentication.token" />
      <zeebe:input source="GET" target="method" />
      <zeebe:input source="=&quot;https://api.example.com/users/&quot; + string(userId)" target="url" />
    </zeebe:ioMapping>
    <zeebe:taskHeaders>
      <zeebe:header key="resultVariable" value="apiResponse" />
      <zeebe:header key="resultExpression" value="={user: response.body}" />
      <zeebe:header key="errorExpression" value="=if response.statusCode &gt;= 400 then bpmnError(&quot;HTTP_ERROR&quot;, string(response.statusCode)) else null" />
    </zeebe:taskHeaders>
  </bpmn:extensionElements>
</bpmn:serviceTask>

应用后，使用 c8ctl bpmn lint process.bpmn 进行验证。

常见问题

• 无法通过 --set 设置 <bpmn:documentation>。 它是单独的 BPMN 子元素，而不是模板属性——请在 apply 后手动编辑。连接器用作 camunda-ai-agents 工具时，这一点尤其重要。
• 只设置生效的属性。 如果未在同一次调用中设置门控属性，条件属性（例如，仅在 authentication.type=bearer 时生效的 authentication.token）会被静默跳过。先确定父级属性值，再设置子属性。
• 出站和入站连接器都需要设置 resultVariable 和／或 resultExpression。 两者都省略时，连接器的响应会被丢弃。
• 使用 {{secrets.NAME}} 设置凭据。 切勿在 --set 中硬编码令牌、API 密钥或 webhook URL。有关本地集群上的密钥引导配置，请参见 camunda-c8ctl。
• 对于尚未确定的值，请使用明确的占位符，例如 TODO_REPLACE_WITH_API_URL 或 PLACEHOLDER_SLACK_CHANNEL。避免使用 ""、"test" 或 "xxx"——这些值可能会被误认为是预期值。

参考资料

详细参考资料请阅读 references/ 中的内容：

• element-template-schema.md — 配置 OOTB 模板的指南，使用 apply --set：属性读取检查清单、binding → BPMN XML 映射表、HTTP 完整示例。完整的编写架构请参见 camunda-connectors-development