camunda-bpmn

Camunda BPMN モデリング

Camunda 8.8 以降向けの、実行可能な BPMN 2.0 プロセスを作成・編集します。Zeebe 拡張とダイアグラム座標を含む、有効な XML を生成します。

前提条件

• Camunda 8.8 以降のクラスター（c8run を使ったローカル環境、SaaS、または Self-Managed）
• c8ctl CLI がインストールされ、設定済みであること（c8ctl add profile） — c8ctl bpmn lint を提供します
• bpmn format には c8ctl ≥ 3.2.0 が必要です。コマンドを利用できない場合は、ユーザーにアップグレードを依頼してください：npm install -g @camunda8/cli

相互参照

• camunda-feel：ゲートウェイ条件、入出力マッピング、タイマー定義で FEEL 式を使用する場合に使います
• camunda-dmn：ビジネスルールタスクの背後にある DMN 判定を作成する場合に使います — <zeebe:calledDecision decisionId="..." resultVariable="..."/>
• camunda-forms：ユーザータスクに紐付ける Camunda Form JSON スキーマを作成する場合に使います
• camunda-connectors：要素テンプレートを使用して、組み込みコネクター（REST、Slack、Kafka など）を設定する場合に使います
• camunda-development：サービスタスクを標準搭載のコネクター、カスタムコネクター、ジョブワーカーのどれで実装するか判断する場合に使います
• camunda-job-workers：サービスタスクの zeebe:taskDefinition type によって起動されるハンドラーコードを実装する場合に使います
• camunda-connectors-development：サービスタスクまたはイベント要素に紐付けるカスタムコネクター（JSON のみのテンプレートまたは Java SDK）を構築する場合に使います
• camunda-process-test：埋め込み Zeebe エンジンに対してプロセスをテストする場合に使います
• camunda-process-mgmt：クラスターにデプロイしてインスタンスを実行する場合に使います
• camunda-ai-agents：AI エージェントをモデリングする場合に使います。AI Agent コネクターで制御するツールをホストするアドホックサブプロセスを使用します

手順

XML 構造

BPMN ファイルを新規作成する際は、bpmn-js の標準スタイルに従ってください。<bpmn:definitions> は 1 行で記述し、インデントにはスペース 2 つを使い、兄弟要素の間に空行を入れず、自己終了形式の <el /> を使用します。そうしないと、Camunda Modeler、Web Modeler、または c8ctl element-template apply を介した往復処理でファイルが再フォーマットされ、Edit の一致が崩れ、差分ノイズが増えます。ルールと具体的なスケルトンについては、references/canonical-style.md を参照してください。

zeebe 名前空間、isExecutable="true"、および modeler:executionPlatform="Camunda Cloud" は必須です。これらがないと、Camunda はプロセスを正しく認識できません。

<bpmndi:BPMNDiagram> ブロックも必須であり、任意の装飾ではありません。c8ctl bpmn lint は DI がない場合（no-bpmndi）をエラーとして報告し、Modeler はこれがないとプロセスをレンダリングできません。すべての <bpmn:process> フロー要素には対応する <bpmndi:BPMNShape> が、すべての <bpmn:sequenceFlow> には対応する <bpmndi:BPMNEdge> が必要です。座標、サイズ、ウェイポイントの規約については、references/layout-rules.md を参照してください。Zeebe は DI のない BPMN でも問題なくデプロイします。DI の欠落が明らかになるのは lint と Modeler での表示時のみなので、デプロイが成功したことをファイルの整形式性の証拠とみなさないでください。

記号のエンコード

XML 属性値内の特殊文字は、必ずエンコードしてください。

• < → <、> → >、& → &、" → "、' → '

コアモデリングルール

開始／終了イベント：

• すべての経路は開始イベント（入力フローなし）から始まり、終了イベント（出力フローなし）に到達します
• ほとんどのプロセスでは None 開始イベントを使用します。外部トリガーには Message、スケジュール実行には Timer を使用します

タスク — 各タスクは原子的なアクションを1つだけ実行します：

• ユーザータスク：人間とのやり取りです。Camunda のユーザータスク実装を使用します。<zeebe:userTask /> を含め、<zeebe:formDefinition formId="X" /> でフォームを関連付けます。<zeebe:assignmentDefinition candidateGroups="..." /> で割り当てます。formId="X" を設定すると、X.form が必須の成果物になります。同じステップで camunda-forms を使って作成するか、最終メッセージで不足を明示してください。c8ctl bpmn lint が確認するのは属性の有無であり、ファイルが解決可能かどうかではありません。非推奨のジョブワーカー方式（<zeebe:userTask /> なしで、formId の代わりに formKey を使用する方式）は記述しないでください。詳しくは references/zeebe-extensions.md の § Form Definition を参照してください。
• サービスタスク：自動処理です。<zeebe:taskDefinition type="..." retries="3" /> が必要です。type はワーカーの登録と完全に一致している必要があります（大文字と小文字を区別します）。標準搭載のコネクターを使用する場合は、camunda-connectors でテンプレートを適用してください。コネクターの入力マッピングを手動で記述しないでください。
• スクリプトタスク：インラインの FEEL 式です。<zeebe:script expression="=..." resultVariable="..." /> を使用します。
• ビジネスルールタスク：DMN 評価です。<zeebe:calledDecision decisionId="X" resultVariable="..." /> を使用します。decisionId="X" を設定すると、対応する X.dmn が必須の成果物になります。camunda-dmn を使って作成してください。
• タスク名には 動詞＋目的語 のパターンを使用します：「請求書を確認する」、「通知を送信する」

ゲートウェイ：

• 排他的（XOR）：経路は1つだけ選択されます。安全なフォールバックフローのために default 属性を設定し、条件フローにラベルを付けます。二択または列挙型の判断（たとえば、承認／却下、はい／いいえ）では、一方の分岐をデフォルトにし、条件は明示的に選択する分岐にのみ設定してください。デフォルトが使用されるのは、他の条件が false と評価された場合に限られます。FEEL の評価エラーから回復することはありません。入力が欠落している可能性がある場合や、型が正しくない可能性がある場合は、比較をガードまたは正規化して、失敗ではなく false を返すようにしてください（たとえば、=if number(string(amount)) != null then number(string(amount)) <= 1000 else false）。すべての出力フローに条件があり、デフォルトがない XOR は生成しないでください。予期しない値、欠落した値、または型の誤った値によって、すべての条件が false になり、CONDITION_ERROR インシデントが発生する可能性があります。
• 並列（AND）：すべての経路が同時に実行されます。同期には必ず対応する結合ゲートウェイを使用してください。
• 包含（OR）：1つ以上の経路が実行されます。これにも対応する結合ゲートウェイが必要です。
• c8ctl bpmn lint の誤った結合に関する警告を修正してください。結合ゲートウェイは分岐の種類と一致している必要があります。

シーケンスフロー：

• 条件には = を先頭に付けた FEEL 式を使用します：

  <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=amount &gt; 1000</bpmn:conditionExpression>
  

BPMN の FEEL 式 — すべての FEEL 式には = を先頭に付ける必要があります：

• ゲートウェイ条件：=riskLevel = "HIGH"
• タイマー期間：="PT7D"（PT7D のみでは拒否されます）
• 入出力マッピング：=customer.name

単純な変数参照を超える内容（関数呼び出し、演算子、コンテキストリテラル、for／every／some）は、コミット前に camunda-feel で検証してください。

ID：説明的な PascalCase を使用します — ReviewInvoice、AmountExceedsLimit、Flow_ToApproval

入出力マッピング

ローカル変数を作成し、変数の伝播を制御します：

<zeebe:ioMapping>
  
  <zeebe:input source="=customer.name" target="customerName" />
  
  <zeebe:output source="=result.status" target="paymentStatus" />
</zeebe:ioMapping>

変数のスコープ、伝播ルール、例について詳しくは、references/zeebe-extensions.md を参照してください。

既存の BPMN ファイルを扱う

BPMN ファイルは大きい場合があります。次のルールに従ってください：

1. Grep を使って要素を検索する — 不必要にファイル全体を読まないでください
2. 変更には Edit を使う — まず Grep で該当箇所を特定してから、正確に編集してください
3. 特定のセクションだけを読む — 必要に応じて offset／limit を使用してください

衛生管理

• canonical bpmn-js スタイルに従ってください。詳しくはreferences/canonical-style.mdを参照してください
• 空の要素は<el />のように自己終了タグにしてください（/>の前にスペースを1つ入れます）
• 一意で説明的な ID を使用してください
• 視覚的なレイアウトのために BPMN DI セクションを含めてください（references/layout-rules.mdを参照）
• 要素に<bpmn:incoming>と<bpmn:outgoing>のフロー参照を含めてください
• 子要素は XSD の順序に従ってください — それ以外の順序ではデプロイ時に拒否されます（cvc-complex-type.2.4.a … One of '{…eventDefinition…}' is expected）：documentation、extensionElements、incoming、outgoing、続いて（イベントの場合）*EventDefinitionです。イベントでは、フロー参照をイベント定義の前に置いてください。c8ctl bpmn format -i <file>を実行すると、子要素がスキーマの順序に並べ替えられます。手書きの XML はデプロイ前に実行してください

リントの反復 — 構造上の完了ゲート

BPMN の編集は、c8ctl bpmn lintでエラーも警告もゼロと報告されるまで、構造上完了したとは言えません。生成、変更、リファクタリング、マージのいずれの場合も、これを各 BPMN タスクの最後の構造確認ステップとして扱ってください。

1. 変更したファイルに対してリンターを実行します。

   c8ctl bpmn lint <path-to-touched-file.bpmn>
   

   c8ctl bpmn lintは BPMN ファイルから Camunda 実行プラットフォームのバージョンを自動検出し、適切な Camunda の既定値を適用します。プロジェクトに.bpmnlintrcがある場合は、そちらが使用されます。標準入力も使用できます：cat process.bpmn | c8ctl bpmn lint。

2. 出力が空でない場合は、報告された問題をすべて修正して、リンターを再実行します。よくあるカテゴリ：

   • no-overlapping-elements — references/layout-rules.mdの間隔ルールに従って DI 座標を調整します
   • fake-join — 結合ゲートウェイの種類を分岐の種類と一致させます（XOR 分岐 → XOR 結合、AND 分岐 → AND 結合）
   • label-required — ラベルが必要なすべての要素に名前を付けます
   • no-disconnected — すべての要素が開始から終了までの完全な経路上にあることを確認します
   • no-implicit-split — 排他ゲートウェイの出力フローには条件とデフォルトを設定する必要があります
   • gateway safety — すべての排他ゲートウェイにdefaultフローがあるか確認します。conditional-flowsを設定しても、この確認の代わりにはなりません。すべての出力フローに条件があっても、一致する値がない場合のフォールバックがないことがあります。
   • superfluous-gateway — 入力が1つ、出力が1つの通過ゲートウェイを削除します

3. リンターの指摘がなくなるまで繰り返します。警告が残っている間は、タスクが構造上完了したと宣言しないでください。BPMN のデプロイは警告があっても通知なく失敗し、クラスターでランタイムインシデントとして表面化します。

警告が明らかに誤検知である場合は、プロジェクトレベルの.bpmnlintrcで明示的に抑制し、最終メッセージでその抑制について伝えてください。黙って無視してはいけません。

リポジトリの決定論的なスモークテストの契約では、固定フィクスチャコマンドは次のとおりです。

c8ctl bpmn lint process.bpmn

一括リントと修正のガイダンス

タスクの対象が単一ファイルではなくディレクトリの場合は、references/bpmn-lint.mdのディレクトリ用ワークフローを使用します。スキップ対象のディレクトリを除外しながら BPMN ファイルを再帰的に検出し、各ファイルをリントし、対象を絞って修正した後、指摘がなくなるまで再度リントします。

動作検証

リントで検出できるのは構造上の問題であり、実行時の動作（FEEL エラー、ワーカー不足、到達不能な終了イベント）は対象外です。リントがクリーンになったら、プロセスを実行して検証します。クラスターを使わずに組み込みエンジンからフィードバックを得られるcamunda-process-testを優先し、それが使えない場合はcamunda-process-mgmtでデプロイしてインスタンスを実行します。

ランタイム互換性ゲート

BPMN の変更をデプロイ／テストに進める前に、デプロイする予定のファイル（単一ファイルまたはディレクトリ一式）を対象に、c8ctl bpmn lint で互換性チェックを実行してください。これは必須のランタイム互換性チェックですが、これだけでデプロイの成功が保証されるわけではありません。

lint で互換性の問題が検出された場合は、次の対応表を参考にしてください。

• implementation/task-definition のエラー：タスクに、BPMN タイプに必要な Zeebe 拡張（<zeebe:taskDefinition>、<zeebe:calledDecision> など）がありません。
• feel / io-mapping のエラー：式が Camunda 8 の有効な FEEL ではありません（たとえば、従来の ${...} や FEEL 以外のマッピング構文）。camunda-feel と照合してください。
• element-type / gateway のエラー：モデルで、対象のランタイムプロファイルではサポートされていない、または推奨されていない構成が使われています。
• timer / event-definition のエラー：タイマーまたはイベントの設定は構造上存在しますが、ランタイム実行には無効です。

互換性チェックの全ワークフロー（対象の選択、ディレクトリ単位の実行、修正ループ）については、references/runtime-compatibility.md を参照してください。

参考資料

詳しい参考資料は references/ から参照してください。

• element-catalog.md — Camunda／Zeebe 属性を含む BPMN 要素タイプの一覧（イベント、タスク、ゲートウェイ、サブプロセス）
• zeebe-extensions.md — 入出力マッピング、変数のスコープ、タスク定義、フォーム定義、シークレット
• layout-rules.md — DI 座標の管理、要素のサイズ、図のレイアウトに関する間隔のルール
• canonical-style.md — bpmn-js の標準 XML スタイル：タグの配置、属性の順序、自己終了形式、手動整形がずれていく理由
• bpmn-lint.md — 単一ファイルとディレクトリ単位の lint ワークフロー、出力の解析、推奨ルールに基づく修正の対応表
• runtime-compatibility.md — デプロイ準備のための互換性 lint ワークフローと修正カテゴリ