camunda-connectors-development

Camunda Connectors 開発

OOTB カタログで必要な連携が見つからない場合は、カスタム Camunda 8 コネクターを構築します。要素テンプレートのインターフェースは共通ですが、Java を記述するかどうかで異なる 2 つの方法があります。

前提条件

• テストに使用する Camunda 8.8 以降のクラスターに接続できること（ローカルの c8run、SaaS、または Self-Managed — camunda-c8ctl を参照）
• 方法 A：クラスター以外の前提条件はありません。JSON テンプレートは手動で作成します。ベースとなる OOTB テンプレートを取得するには、c8ctl element-template get <id> を使用します。
• 方法 B：Java 17 以降、Maven 3.8 以降（または同等の Gradle）、および作成したコネクター JAR のホスティングに使用する JVM オプションが必要です。JDK と Maven ツールチェーンをローカルにインストールする方法については、camunda-development を参照してください。

関連項目

• camunda-development：コネクターを構築するのが適切な方法か（OOTB コネクターやジョブワーカーを使うべきか）を、まず判断します。
• camunda-connectors：OOTB コネクターの検索と適用に使用します。ここで拡張するカタログです。
• camunda-job-workers：連携ロジックを再利用可能なコネクターではなくアプリケーションコードに置く場合に使用します（意思決定マトリクスの方法 C。ワーカーはアウトバウンド専用です）。
• camunda-bpmn：コネクターを関連付ける BPMN 要素の作成に使用します（アウトバウンドではサービス タスク、インバウンドでは開始／中間／境界イベントまたは受信タスク）。
• camunda-feel：テンプレートプロパティの事前入力、および入出力マッピングのバインドに使用する FEEL 式について説明します。
• camunda-process-test：カスタムコネクターを通じてプロセスを実行するエンドツーエンドテストに使用します。

カスタムコネクターを作成する場合

まず camunda-development を確認してください。ここでの意思決定マトリクスを簡潔にまとめると、次のとおりです。

• OOTB コネクターで対応できる → OOTB テンプレートを使用します。以上です。
• 一般的なプロトコル（REST、SOAP、GraphQL、Kafka、RabbitMQ、AWS SQS/SNS など）を使用した単一の API 呼び出しで、Java を使用できる → 方法 A：既存のプロトコルコネクターの JSON テンプレートをカスタマイズします。Java も追加のデプロイも不要です。
• 複数ステップのオーケストレーション、独自プロトコル、HTTP 以外の I/O、または重要なビジネスロジックが必要で、Java スタックを使用できる → 方法 B：Connectors SDK を使用してカスタム Java コネクターを作成します。
• Java 以外の SDK を使用する場合、またはロジックを既存のアプリケーション内に置く場合 → ジョブワーカーを作成します。ワーカーでインバウンドトリガーを処理することはできません。

アウトバウンドとインバウンド

2 つの方向は対称ではありません。エンジンの外部から発生したイベントによってプロセスを開始できるのは、インバウンドコネクターだけです。ワーカーでインバウンドを置き換えることはできません。インバウンドはコネクターフレームワークが担います。

• アウトバウンド：プロセストークンがサービスタスクに到達すると、コネクターが外部システムを呼び出し、結果が変数として返されます。方法 A と方法 B は、どちらもアウトバウンドに対応しています。
• インバウンド：外部システムがイベントを発生させます（HTTP リクエスト、メッセージキューへの配信、スケジュールされたポーリング）。コネクターはそのイベントをプロセスに関連付け、新しいインスタンスを開始するか（開始イベント）、待機中のインスタンスを続行します（中間キャッチイベント、境界イベント、メッセージ開始イベント、受信タスク）。方法 B のみが対応します。方法 A のプロトコルテンプレートはアウトバウンドプロトコルコネクターを基盤とします。インバウンド Webhook コネクターには独自の OOTB テンプレートがあり、これを直接カスタマイズします。

インバウンドには 3 つの種類があり、それぞれ異なる SDK の形式が使われます。

• Webhook — ランタイムはデプロイ済みのプロセスごとに HTTP エンドポイントを公開し、外部システムからそこへ POST リクエストを送信します。
• サブスクリプション — ランタイムはメッセージブローカーとの接続を確立し、メッセージを消費します（Kafka、RabbitMQ、AWS SQS など）。
• ポーリング — ランタイムはプロセスに代わって、定期的に外部システムを呼び出します。

イベントをエンジンに渡すライフサイクル（activate / deactivate）と correlateWithResult の仕様については、references/connector-sdk-inbound.md を参照してください。

パスを選択する

パス	選択する場面
パス A — プロトコルコネクター上の JSON のみのテンプレート (参照)	サポートされているプロトコル（REST/SOAP/GraphQL/Kafka/RabbitMQ/AWS メッセージング）を介した単一の呼び出しで完結するアウトバウンド連携です。Java を記述せずに、Modeler でドメインに即した UI を実現できます。リポジトリ内の単一の JSON ファイルとして提供されます。
パス B — SDK を使ったカスタム Java コネクター ([参照：アウトバウンド、インバウンド])	パス A では対応できないあらゆるケースです。複数ステップのオーケストレーション、独自プロトコル、HTTP 以外の I/O、インバウンドトリガー（Webhook／サブスクリプション／ポーリング）、またはプロセス間でバージョン管理された成果物として再利用する必要があるロジックが含まれます。Java 17 以降とホスティング方法の決定が必要です。

パス A のプロトコルとの重複がなく、パス B では大がかりすぎる場合に、ジョブワーカーに洗練された Modeler UI を提供する自然な方法として、JSON テンプレートも使えます。references/element-template-json.md を使ってテンプレートを手動で作成し、ワーカーの zeebe:taskDefinition type にバインドしてください。これはあくまでワーカーであり、コネクターではありません。

エレメントテンプレート — 共通の基盤

どちらのパスでも、エレメントテンプレート JSON ファイルが生成されます。スキーマは共通で、異なるのはファイルの作成方法です。

• パス A：プロトコルコネクターの公開済みテンプレートを c8ctl element-template get <id> で取得し、ベースとしてカスタマイズします。"type": "Hidden" を使ってインフラストラクチャのプロパティ（URL、メソッド、認証）を非表示にし、FEEL で事前入力して、ドメイン固有の入力のみを公開します。
• パス B：コネクタークラスに @ElementTemplate アノテーションを付け、Maven プラグインでビルド時に JSON を生成する（references/element-template-generator.md）か、手動で作成します。

プロトコルコネクターだけでなく、任意の OOTB テンプレートを特化させる

「インフラストラクチャを隠し、ドメイン入力のみを公開する」パターンは、汎用プロトコルテンプレートだけでなく、あらゆる OOTB テンプレートで使えます。カスタマイズしたテンプレートが、基盤となるジョブワーカーが想定する入力マッピング（zeebe:taskDefinition type と zeebe:input の形式がデータ契約です）を書き込む限り、ワーカーが受け取るペイロードは同じで、Modeler UI だけが異なります。

camunda/connectors にある具体例：

• connectors/openai/element-templates/openai-connector.json — OpenAI の完全なテンプレートです。特化版では、システムプロンプトやモデル選択を非表示にし、ドメイン入力のみを公開できます。
• connectors/github/element-templates/github-connector.json — 基盤となるジョブワーカー向けの特化した UI です。
• connectors/github/element-templates/github-webhook-connector-receive.json — 汎用 Webhook インバウンドコネクターを、GitHub 固有の Webhook UI として公開しています。
• connectors/hugging-face/element-templates/hugging-face-connector.json — 基盤となる REST 呼び出しに対して、Hugging Face の形式に合わせた UI を提供します。

c8ctl element-template get <id> を使ってベーステンプレートを取得し、ワーカーが読み取るバインディングを維持しながら、プロパティを非表示／ハードコード／名前変更してください。

references/element-template-json.md は、両方のパスで使うスキーマのリファレンスです。プロパティタイプ、バインディングタイプ、FEEL／制約／条件／generatedValue の機能、および各 BPMN 添付先に対応するテンプレートのバリエーションを説明しています。

フィールド順序のルール： 別のプロパティの FEEL value で使用されるプロパティは、properties 配列内でそのプロパティより前に記述する必要があります。順序が逆の参照は、エラーにならずに null として評価されます。同じルールは、パス A のカスタマイズと、手動で作成するパス B のテンプレートにも適用されます。

共通機能（Path A と Path B）

• シークレット — 要素テンプレートと Java コードは、実行時に {{secrets.NAME}} プレースホルダーを解決します。シークレットを BPMN、テンプレートのデフォルト値、またはハードコードされた文字列に保存しないでください。スタンドアロンランタイムは、デフォルトで SECRET_* 環境変数から読み取ります（8.9 以降）。
• 組み込み関数 — テンプレートのデフォルト値と FEEL 入力では、getText、base64、createLink などの組み込み関数を呼び出して、コネクターに値を渡す前に変換できます。
• Camunda Documents — バイナリコンテンツ（PDF、画像）を生成または消費するコネクターは、Camunda Documents をネイティブに処理します。ワーカーでは、この接続処理を独自に実装する必要があります。
• 結果変数／結果式／エラー式 — どちらのパスでも、要素テンプレートのヘッダーを介して標準の 出力マッピング グループ（resultVariable、resultExpression）と エラー処理 グループ（errorExpression）が公開されます。バインディングの形式については、references/element-template-json.md を参照してください。

登録とホスティング

Path B には Path A にはないホスティングの選択肢があります。JAR をどこかで実行する必要があります。選択肢は 4 つあり、references/registration-and-hosting.md で説明しています。

• SaaS 管理ランタイム — Camunda が標準コネクターを実行します。管理ランタイムではカスタム JAR はサポートされないため、SaaS で Path B を利用するには Hybrid モード（下記）が必要です。
• Self-Managed スタンドアロン — カスタムコネクター JAR をアプリケーションディレクトリにマウントした camunda/connectors:X.Y.Z Docker イメージを使用します。
• Self-Managed 組み込み — spring-boot-starter-camunda-connectors スターターを使用する Spring Boot アプリケーションです。アプリケーションでコネクターと独自のビジネスコードの両方をホストします。
• Hybrid — スタンドアロンランタイムを自分の環境で実行しながら、SaaS クラスターに接続します。エンジンが SaaS でも、コネクターを自分のネットワーク境界内で実行する必要がある場合（プライベートネットワークへのアクセス、オンプレミスの依存関係、カスタム JAR）に必須です。

SPI 登録と Spring Bean 登録は、ホスティングの選択とは独立していますが、選択肢を制約します。 SPI 登録では META-INF/services/... ファイルが作成され（Maven プラグインのデフォルト動作）、スタンドアロンランタイムで動作します。Spring Bean 登録（コネクタークラスに付ける @Component）には組み込みの Spring Boot ランタイムが必要であり、SPI ファイルの生成を抑制するために、Maven プラグインで <writeMetaInfFileGeneration>false</writeMetaInfFileGeneration> を指定する必要があります。同じクラスを両方の仕組みで登録すると、検出が重複します。

Hybrid テンプレート

Path B をスタンドアロンランタイム経由で SaaS クラスターに対して実行する場合（Hybrid ホスティング）、Maven プラグインの <generateHybridTemplates>true</generateHybridTemplates> フラグによって、コネクターごとに *-hybrid.json テンプレートが別途生成されます。Hybrid テンプレートは、コネクターのタスクタイプを、SaaS エンジンが検出してスタンドアロンランタイムにルーティングできるジョブワーカー形式のバインディングに切り替えます。このフラグを指定せずに標準テンプレートを SaaS にデプロイすると、実行時にジョブを受け取れません。

よくある落とし穴

• トレーニング時の記憶をもとにテンプレート ID やプロパティ名を捏造する — コードやドキュメントで ID、グループ、プロパティを指定する前に、c8ctl element-template search "<keyword>" と c8ctl element-template get-properties <id> を使用して、最新の OOTB カタログで確認してください。
• Spring Bean 登録を使用する際に <writeMetaInfFileGeneration>false</writeMetaInfFileGeneration> を忘れる — SPI ファイルと @Component が同じクラスを二重に登録するため、実行時に 2 つのインスタンスが生成され、2 つ目が 1 つ目をひそかに上書きします。
• フィールドの順序による不具合 — FEEL の value が後に宣言された兄弟プロパティを参照しているプロパティは、実行時に null と評価されます。Modeler では警告されず、コネクターには空の入力が渡されます。
• SaaS に対してスタンドアロンで実行する際に Hybrid テンプレートを省略する — 標準テンプレートのタスクタイプは、SaaS からスタンドアロンのランタイムへルーティングできません。<generateHybridTemplates>true</generateHybridTemplates> を設定し、-hybrid バリアントをデプロイしてください。
• 非対応プロトコルで Path A を使用する — Path A の対応範囲はプロトコルコネクターのカタログ（REST、SOAP、GraphQL、Kafka、RabbitMQ、AWS メッセージング）に限られます。「TCP 上のカスタムバイナリプロトコル」テンプレートにはレイヤーとして重ねるものがないため、Path B を使用してください。
• 受信 Webhook をジョブワーカーとして扱う — 受信コネクターはプロセス定義のデプロイ時に有効化され、デプロイが削除されると無効化されます。ポーリング対象のインスタンスごとのジョブはありません。ライフサイクルは activate(InboundConnectorContext) / deactivate() であり、ジョブごとのハンドラーではありません。

参考資料

詳しくは references/ のドキュメントを参照してください。

• protocol-connector-templates.md — Path A の手順：c8ctl によるベーステンプレートの取得、URL／メソッド／認証の非表示化、FEEL による事前入力、カスタムグループ、REST Countries を使った実例、テンプレート生成ツールへの簡単なリンク
• connector-sdk-outbound.md — OutboundConnectorProvider + @Operation（モダン）、OutboundConnectorFunction（レガシー）、@Variable / @Header、ConnectorException、Jakarta Validation
• connector-sdk-inbound.md — InboundConnectorExecutable、3 つの種類、ライフサイクル、correlateWithResult / CorrelationResult
• element-template-json.md — スキーマリファレンス：トップレベルフィールド、プロパティタイプ、バインディングタイプ、プロパティ機能、BPMN のアタッチメントごとのテンプレートバリアント
• element-template-generator.md — Maven プラグインの設定、@ElementTemplate アノテーション、generateHybridTemplates、versionHistoryEnabled、writeMetaInfFileGeneration
• registration-and-hosting.md — SPI と Spring Bean の登録、SaaS／SM スタンドアロン／SM 組み込み／Hybrid のホスティングモデル