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：設定済みプロセスをクラスターにデプロイする際に使用します

説明

エレメントテンプレート

エレメントテンプレート（コネクターテンプレートとも呼ばれます。この 2 つの用語は Camunda のドキュメントとツールで同じ意味で使われています）は、コネクターの設定をまとめた JSON ファイルです。各テンプレートでは、次の項目が定義されています。

• ジョブを処理するコネクターランタイムを識別するタスクタイプ
• BPMN XML（入力マッピング、タスクヘッダーなど）に対応付けるバインディングを備えたプロパティ
• ユーザーの選択に応じて有効になるプロパティを制御する条件
• ユーザー入力（必須フィールド、URL パターンなど）を検証する制約
• プロパティを論理的なセクション（認証、エンドポイント、出力、エラー処理）に整理するグループ

プロパティフィールドとバインディングから BPMN XML への対応付けについては、references/element-template-schema.md のガイドを参照してください。テンプレート作成用の完全なスキーマは camunda-connectors-development にあります。

検索によるコネクターの検出

テンプレート ID は推測したり記憶を頼りにしたりせず、必ず c8ctl element-template search で検索して確認してください。 テンプレート 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 要素の種類（メッセージ開始イベント、中間キャッチイベント、境界イベント、受信タスクなど）ごとに 1 つのテンプレートがあります。search は各バリエーションを返すため、モデリングする BPMN 図形に合ったものを選択してください。

テンプレートの調査

適用前に確認する内容は、次の2つのコマンドで調べられます。

• c8ctl element-template info <id> [--engine-version <x.y.z>] — メタデータカード（適用対象、エンジンの制約、説明、ドキュメントへのリンク）を表示します。--engine-version を指定すると、そのエンジンと互換性のある最新バージョンを解決します。コネクターについて詳しくない場合に便利です。
• c8ctl element-template get-properties <id> [<name>...] [--engine-version <x.y.z>] — 設定可能なプロパティを、名前と説明に絞ってグループ別に表示します。位置引数の名前を指定でき（シェル形式のグロブも使用できます。引用符で囲んでください）、--group <id> で対象を絞り込めます。--engine-version を指定すると、そのエンジンと互換性のある最新バージョンを解決します。各プロパティのカードに Required、FEEL、Active when、Pattern、Default、Choices を表示するには、--detailed を追加します。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 要素へのテンプレートの適用

サービスタスク（またはその他のサポート対象要素）にテンプレートを適用します。1回の呼び出しで、完全に設定されたコネクターが生成されます。

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 と互換性のある最上位バージョンが自動的に解決されます。少なくとも1回、c8ctl element-template sync を実行している必要があります。
• ローカルファイルのパス（例：./my-custom-template.json）。同期は不要です。
• https:// URL（GitHub の blob URL は raw content に自動的に書き換えられます）。同期は不要です。

-i を指定すると、BPMN ファイルを直接変更します。-i を指定しない場合、変更後の XML が標準出力に出力されます。プレビュー、出力のリダイレクト、または他のツールとの組み合わせに便利です。

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 は、--set で指定したキーだけでなく、デフォルト値を持つすべての有効なプロパティを BPMN に反映します。対象には <zeebe:input>、<zeebe:output>、<zeebe:taskHeaders>、<zeebe:property> の各エントリーが含まれます。デフォルト値は適用時点のものが記録されるため、テンプレートに後から新しいデフォルト値が追加されても、この BPMN には古い値が保持されます。

再適用。 省略した --set キーは現在の XML 値が維持されるため、プロパティを1つだけ再適用しても、ほかの値には影響しません。例外として、ドロップダウンは再適用のたびにテンプレートのデフォルト値にリセットされます。

要素を新しいテンプレートに更新する — update (c8ctl 4.6.1+)

update は、すでにテンプレートが適用されている要素を、その新しいバージョン（または --to <id>[@<n>]、パス、URL で指定した別のテンプレート）に移行し、値を引き継ぎながら変更内容を報告します。新しいカタログバージョンに対して apply を再実行するとドロップダウンがリセットされるため、代わりに update を使用してください。

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> は現在使用中のテンプレートです。1つのコマンドで指定できる ID は1つです。要素 ID を指定しない場合は、そのテンプレートを使うすべての要素（バージョンを問わない）が更新されます。要素 ID を指定した場合は、その要素のみが更新され、<template-id> を使用している必要があります。
• 更新先。 デフォルトでは、BPMN の executionPlatformVersion に適合する最新バージョンが選ばれます。先に sync を実行してください。
• 値。 キー名が同じ値は引き継がれます。更新先で別のキーにバインドされている値は、更新先の metadata.migratesFrom にある移行レシピ、--recipe <file>、または --map <from>=<to> がある場合にのみ移動されます。それ以外の値は報告されます。
• レポート。 マーカーは + が追加、~ が変更、> が移動、- が削除を示し、レシピに関する注記も表示されます。--json は構造化形式を出力するため、エージェントにはこちらを推奨します。
• 安全性。 選択したすべての要素の移行が成功する場合に限り、ファイルは一度だけ書き込まれます。1つでも失敗する場合、または書き込みに --allow-lossy が必要な場合、--dry-run は終了コード 1 で終了します。削除される値をすべて確認してから --allow-lossy を指定してください。

コネクターごとのレシピについては、まだここでは説明していません。AI Agent v1 から v2 への移行については、camunda-ai-agents を参照してください。

結果のマッピング — resultVariable と resultExpression

コネクターには 出力マッピング グループに、コネクターの完了時にプロセススコープに書き戻す値を制御するプロパティが 2 つあります。

• resultVariable — 生のレスポンスを受け取る単一のプロセス変数名です。通常の文字列で、= プレフィックスは付けません。後続のタスクでレスポンス全体を 1 つの名前で参照する場合に使用します。
• resultExpression — レスポンスに対して評価され、その結果がプロセススコープにマージされる FEEL 式です。= プレフィックスが必要です。特定のフィールドの抽出、名前の変更、派生値の計算に使用します。

両方を同時に設定できます。resultVariable で生のレスポンスを取得し、resultExpression でそれと並行して名前付き変数を整形します。どちらも設定されていない場合、レスポンスは破棄され、後続のタスクからこのコネクターによる新しい変数は参照できません。

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

同じ仕組みは インバウンドコネクター にも適用されます。たとえば、Slack インバウンドコネクターでは、同じ出力マッピンググループに resultVariable と resultExpression が表示されます。トリガーが実行されると、エンジンは受信イベントのペイロードをプロセススコープに書き込みます。これは、サービス タスクの完了時にアウトバウンドコネクターがレスポンスを書き込むのと同じ動作です。

コネクターを AI エージェントのツール として使用する場合、その出力は 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 で検証してください。

よくある落とし穴

• <bpmn:documentation> は --set では設定できません。 テンプレートのプロパティではなく、個別の BPMN 子要素です。apply の後に手動で編集してください。コネクターを camunda-ai-agents のツールとして使用する場合は、特に重要です。
• 有効なプロパティのみ設定してください。 条件付きプロパティ（例：authentication.token は authentication.type=bearer の場合にのみ適用されます）は、制御するプロパティが同じ呼び出しで設定されていない場合、通知なしにスキップされます。まず親の値を決めてから、子のプロパティを設定してください。
• アウトバウンドコネクターとインバウンドコネクターの両方で、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 — apply --set を使用して標準テンプレートを設定するためのガイドです。プロパティを読み取る際のチェックリスト、バインディングから BPMN XML へのマッピング表、HTTP の実例を掲載しています。テンプレート作成スキーマ全体については、camunda-connectors-development を参照してください。