camunda-development

Camunda 開発

Camunda 8.8 以降の統合コードを書く前に、すぐに使えるコネクター、カスタムコネクターテンプレート、Connectors SDK を使用したカスタム Java コネクター、ジョブワーカーのどれを使うか決めてください。このスキルは概要を示すための薄いレイヤーです。ここで紹介する各方法には、それぞれに特化したビルドスキルがあります。

相互参照

• camunda-connectors：既存のすぐに使えるコネクターテンプレートを検索して適用する場合に使用します
• camunda-connectors-development：カスタムコネクター（プロトコルコネクター上の JSON のみのテンプレート、または Connectors SDK を使用した Java コネクター。アウトバウンドとインバウンドの両方に対応）を構築する場合に使用します
• camunda-job-workers：Java、Spring Boot、TypeScript でジョブワーカーを実装する場合に使用します
• camunda-bpmn：コネクターまたはワーカージョブをホストする BPMN 要素（サービスタスク、メッセージイベントなど）に使用します
• camunda-process-test：完成したプロセスをテストする場合に使用します

判断マトリクス

質問を上から順に確認してください。答えが「はい」となる最初の質問で確認を終了します。

1. すぐに使える（OOTB）コネクターで統合を実現できますか？ c8ctl element-template search "<keyword>" を使ってローカルカタログを検索してください（camunda-connectors を参照）。テンプレートが対象システムに適合する場合は、そのまま使用します。ここで終了です。

2. 一般的なプロトコル（REST、SOAP、GraphQL、Kafka、RabbitMQ、AWS SQS/SNS など）を使った単一の API 呼び出しで統合でき、再利用可能でモデラーにとって使いやすい構成要素が必要ですか？ → 方法 A — プロトコルコネクター上の JSON のみのテンプレート。 Java は不要で、別のランタイムも必要ありません。プロトコルコネクターの公開済みテンプレートをカスタマイズします。URL に FEEL を事前入力し、メソッド／ベース URL／認証を非表示にして、ドメイン固有のプロパティだけを公開します。camunda-connectors-development を参照してください。

3. ロジックは単一の API 呼び出しを超えるもので（独自プロトコル、状態を伴う複数ステップのオーケストレーション、HTTP 以外の I/O、カスタムのインバウンドトリガー）、チームは Java を使用していますか？ → 方法 B — Connectors SDK を使用したカスタム Java コネクター。 アノテーション駆動で、要素テンプレートを自動生成し、シークレット／組み込み関数／Camunda Documents に対応しています。アウトバウンドとインバウンドの両方で動作します。camunda-connectors-development を参照してください。

4. それ以外の場合（Java 以外のスタック、ロジックがすでにアプリケーション内にある場合、または低レベルの Zeebe API（ジョブストリーミング、カスタムアクティベーション）が必要な場合）。 → 方法 C — ジョブワーカー。 公式 SDK（ここでは Java、Spring Boot、TypeScript を扱います。他の SDK でも同じパターンを使用します）のいずれかを使って、アプリ内にハンドラーを実装します。ワーカー用のモデラー UI も必要な場合は、要素テンプレート JSON を手動で作成してください。camunda-job-workers を参照してください。

比較：ジョブワーカーとコネクター（SDK）

項目	ジョブワーカー	コネクター（SDK）
言語	公式 SDK（Java、Spring Boot、TypeScript など）	Java のみ
提供方法	実行するアプリケーションに紐付けられる	ライブラリとして提供され、任意の Connector Runtime にデプロイ可能
環境間での再利用性	難しい — プロジェクトごとに再接続が必要	簡単 — 同じ JAR を任意のランタイムに配置
焦点	Zeebe クライアントの全機能（アクティベート、完了、失敗、再試行）	ビジネスロジックに専念。Zeebe との接続はランタイムが処理
シークレット	独自に実装（環境変数、シークレットマネージャー）	{{secrets.NAME}} の解決機能を内蔵
低レベルの Zeebe API	はい	いいえ
タスク用のモデラー UI	任意 — 要素テンプレート JSON を手動で作成	標準化 — @ElementTemplate から生成
要素テンプレートの自動生成	なし — JSON を手動で作成	Maven プラグインがアノテーションから生成
組み込み関数（getText、base64 など）	いいえ	はい
Camunda Documents の処理	手動	内蔵
インバウンドトリガー	いいえ（アウトバウンドジョブのみ）	はい（Webhook／Subscription／Polling）

この表は、判断マトリクスの理由を示しています。コネクターは言語の選択肢を狭める代わりに、再利用性と豊富な機能を提供します。一方、ワーカーはその機能を絞る代わりに、言語を選べることと Zeebe に直接アクセスできることを提供します。

作業例 — マトリックスの適用

「注文が承認されたら Slack に通知します。チームでは Node.js を使用しています。」

1. OOTB コネクターはありますか？ c8ctl element-template search "slack" を実行すると、io.camunda.connectors.Slack.v1 が返されます。ボットメッセージ操作で、カスタム UI の要件がない単発の通知に対応できます。→ これを使用します。 ここで終了です。

「社内の HTTP 価格設定 API にジョブを送信します。チームでは Java を使用しています。Modeler で公開する項目を customerId、productSku、quantity のみにした、再利用可能なコネクターが必要です。」

1. OOTB はありますか？一致するテンプレートはありません。
2. 一般的なプロトコルを介した単一の API 呼び出しで、Java チームが再利用可能なビルディングブロックを必要としていますか？ はい — REST です。→ パス A。 公開済みの HTTP REST コネクターテンプレートを使用し、customerId からリクエスト URL を組み立てる FEEL 式を使って URL を事前入力し、メソッド／ベース URL／認証フィールドを非表示にして、ドメインプロパティ 3 つだけを公開します。JSON のみで、ランタイムとしてデプロイするものはありません。camunda-connectors-development を参照してください。

「SFTP サーバーから請求書を定期的に取得し、ファイルごとにプロセスを開始します。チームでは Java を使用しています。」

1. OOTB はありますか？要件に合う SFTP プル型の開始イベントコネクターはありません。
2. 一般的なプロトコルを介した単一の API 呼び出しですか？いいえ — SFTP、カスタムのポーリング間隔、インバウンドトリガーです。
3. 複雑な統合で、Java チームですか？ はい。→ パス B の ポーリング インバウンド方式を使用します。Connectors SDK で構築します。camunda-connectors-development を参照してください。

「チームで既に使用している Node.js のスコアリングサービスを使って、顧客レコードを評価します。」

1. OOTB はありますか？ありません。
2. 一般的なプロトコルを介した単一の API 呼び出しで、Java チームですか？チームでは Node.js を使用しています — 言語の条件に合いません。（スコアリングサービスを Java REST テンプレートでラップすることも できます が、ロジックは既に Node.js アプリにあり、コネクターを保守する Java チームもありません。）
3. Java チームですか？いいえ。→ パス C のジョブワーカーを使用します。TypeScript SDK を介して、既存の Node.js サービスが score-customer ジョブを処理するように接続します。camunda-job-workers を参照してください。

1 つのプロジェクト内での併用

ワーカーとコネクターは、プロジェクト単位ではなく、タスクごとに選択します。1 つの Spring Boot アプリケーションで、Camunda Spring Boot Starter を介したジョブワーカーと、spring-boot-starter-camunda-connectors を介した組み込みコネクターランタイムを並行してホストできます — Connectors SDK 自体も Spring Boot Starter を基盤としています。統合ごとに適切な構成を選択してください。プロジェクト全体を 1 つのパスに統一する必要はありません。

複数成果物のデリバリーオーケストレーション（BPMN + ワーカー + DMN + フォーム）

プロセスが複数のサービス タスク、ユーザー タスク、ビジネスルール タスクにまたがる場合、場当たり的に生成するのではなく、構造化された引き継ぎとして実装をオーケストレーションします。

1. BPMN に基づいて明確な実装計画を作成します。
   • サービス タスク／メッセージ イベントの統合ポイント → コネクターまたはワーカーの経路
   • formId を持つユーザー タスク → .form 成果物
   • decisionId を持つビジネスルール タスク → .dmn 成果物
2. 成果物を生成する前に、計画をレビューして承認します。
3. 安全に実施できる場合は、独立した領域を並行して実装します。
   • ワーカー／コネクター
   • DMN の決定
   • フォーム
   • BPMN の実行配線の更新
4. 各領域の検証ループを実行します。
   • BPMN：c8ctl bpmn lint（必要に応じて互換性チェックも実行）
   • DMN：npx --yes dmnlint（構造）+ FEEL／ヒットポリシーのテスト実行（camunda-dmn を参照）
   • フォーム：JSON スキーマの妥当性 — 必須フィールド、schemaVersion、コンポーネントの key の一意性（camunda-forms を参照）
5. デプロイ前に、成果物間の配線を監査します。
   • コネクター以外のすべての taskDefinition type（通常、コネクター形式のコロンを含まない値。例：check-credit）がワーカーによって実装されていること。コネクター ランタイムのタスクタイプ（例：io.camunda:slack:1）はカスタム ワーカーではなく、コネクターのテンプレート／ランタイムによって解決されます。
   • 参照されているすべての formId が存在し、フォームの id と一致していること。
   • 参照されているすべての decisionId が、デプロイ済みの DMN リソースに存在すること。
6. 検証に合格したカテゴリのみをデプロイします。カテゴリを意図的に除外する場合は、そのことを明記し、修正されるまでリリースステータスを部分的な状態に保ちます。

これにより、大規模な Camunda のデリバリーを予測可能かつレビュー可能にし、安全に反復できるようになります。

インバウンドはコネクターの役割です

インバウンド トリガー — 外部システムからプロセスに流入するイベント — は、Connectors SDK のみを使用して実装します。インバウンドにジョブ ワーカーを使う経路はありません。ジョブ ワーカーが処理するのは、エンジンがすでにアクティブ化したアウトバウンド ジョブのみです。

SDK は 3 種類のインバウンド方式をサポートしており、選択した方式によって、要素テンプレートが適用される BPMN 要素の種類（メッセージ開始イベント、中間キャッチ イベント、境界イベントなど）が決まります。

• Webhook — ランタイムが HTTP リスナーをホストし、外部システムから呼び出します。
• Subscription — ランタイムがメッセージ ブローカー（Kafka、RabbitMQ、AMQP など）への長時間接続を開き、イベントを消費します。
• Polling — ランタイムがスケジュールに従って外部エンドポイントをポーリングします。

統合がインバウンドの場合、判定マトリクスでは経路 A と B のみが選択肢となり、経路 C は適用されません。camunda-connectors-development を参照してください。

ローカルの前提条件

判定マトリクスは経路を示します。その経路を利用するには、ローカルのツールチェーンが動作している必要があります。各ワークフローの概要（各経路が必要とするツール — Node.js、JRE、JDK + Maven、Docker）、OS に依存しない確認用ワンライナー、複数の経路に共通する注意点（JAVA_HOME と PATH の違い、Docker デーモンと CLI の違い、camunda/zeebe:latest を事前にプルしない理由）については、references/prerequisites.md を参照してください。各経路の具体的な最小バージョンは、リンク先のスキルに記載されています。これらは Camunda のリリースごとに変わります。

参考資料

• prerequisites.md — ローカル開発環境のマトリクス（ワークフローごとの JDK／Node.js／Maven／Docker）、確認用ワンライナー、ツールに関する注意点。