camunda-process-mgmt

Camunda プロセス管理

c8ctl を使用した Camunda 8.8 以降のクラスター向けランタイム操作です。リソースのデプロイ、インスタンスの開始、状態の確認、インシデントの解決、タスクの完了、メッセージの発行、インスタンスのキャンセルを行えます。モデルの作成後に行うすべての操作を対象とするスキルです。

前提条件

• Camunda 8.8 以降のクラスター（c8run によるローカル環境、SaaS、または Self-Managed）
• c8ctl CLI がインストールされ、対象クラスター用のプロファイルが設定されていること。セットアップについては camunda-c8ctl を参照してください

相互参照

• camunda-c8ctl：c8ctl のセットアップ、クラスターの安全性、共通の規則（フラグ、プロファイル、出力モード）に使用します
• camunda-bpmn：デバッグ中に見つかった BPMN プロセスの問題の修正に使用します
• camunda-dmn：DMN の判定に関する問題の修正に使用します。EXTRACT_VALUE_ERROR／DECISION_EVALUATION_FAILED のインシデントは、通常、判定ファイルに原因があります
• camunda-connectors：デバッグ中に見つかったコネクター設定の問題の修正に使用します
• camunda-job-workers：インシデントの原因がプロセスモデルではなくハンドラーコードにある場合に使用します。zeebe:taskDefinition type のワーカー側を扱います
• camunda-connectors-development：インシデントの原因がテンプレート設定ではなく、カスタムコネクターのランタイム／登録／ホスティングにある場合に使用します
• camunda-feel：インシデントで発生した FEEL 評価エラー（EXTRACT_VALUE_ERROR、CONDITION_ERROR）の診断に使用します
• camunda-process-test：組み込み Zeebe エンジンを使用したプロセスのテストに使用します

手順

リソースのデプロイ

クラスターの安全性 — ローカルの c8run 以外にデプロイする場合は、必ず事前に確認してください。

現在アクティブな c8ctl プロファイルが、前回のセッションで共有クラスター（prod、staging、顧客名など）を指す状態のままかもしれません。その場合、c8ctl deploy process.bpmn をそのまま実行すると、気付かないうちにそのクラスターへ書き込みます。

• 最初に c8ctl which profile を実行します。共有環境を示す名前の場合は、デプロイ前にユーザーに確認してください。
• deploy およびその他の変更を伴うコマンド（run、cancel、resolve、complete、publish、watch）では、必ず --profile=<name> を明示的に指定してください。
• 検証用デプロイ（変更が機能するかを一度実行して確認する場合）では、稼働中の c8run クラスターに対して --profile=local を使用してください。クラスターが稼働していない場合は、c8ctl cluster start を実行します。

クラスターの安全性に関する正式なルールについては、camunda-c8ctl を参照してください。

例 — BPMN ファイルを 1 つ、ローカルプロファイルにデプロイします。

c8ctl deploy process.bpmn --profile=local

複数のリソース（BPMN、DMN、フォーム）を一度にデプロイします。

c8ctl deploy process.bpmn decision.dmn approval-form.form

ディレクトリ全体を再帰的にデプロイします。

c8ctl deploy ./my-project

デプロイ前のチェック（推奨）：

1. デプロイ前に BPMN をリントします。

   c8ctl bpmn lint process.bpmn
   

2. DMN ファイルとフォームファイルがある場合は、それらを検証してから（camunda-dmn と camunda-forms のワークフローを参照）、準備が整ったリソースのみをデプロイします。

Spring Boot のリソースツリーに関するヒント：

• デプロイ対象を src/main/resources/ 以下に置いているプロジェクトでは、processes/、decisions/、forms/ のパスを明示してデプロイすることをおすすめします。
• デプロイできないファイル（application.yaml、application.properties など）が含まれている場合、親ディレクトリである src/main/resources 全体のデプロイは避けてください。

例：

c8ctl deploy \
  src/main/resources/processes \
  src/main/resources/decisions \
  src/main/resources/forms \
  --profile=local

デプロイ後に確認します。

c8ctl list pd
c8ctl search pd --iname="MyProcess"

デプロイのたびに、含まれる各リソースの新しいバージョンが作成されます。c8ctl list pd --fields Key,Name,Version を使用すると、バージョンを確認できます。

プロセスインスタンスの開始

目的に応じて開始コマンドを選択します。

必要な操作	コマンド
開始してすぐに戻る（デフォルト）	c8ctl create pi --id <bpmnProcessId> [--variables '{...}']
デプロイと開始を一度に行う	c8ctl run <file.bpmn> [--variables '{...}']
インスタンスの完了まで待機する	c8ctl await pi --id <bpmnProcessId> [--variables '{...}']

デプロイ済みプロセスのインスタンスを作成します。

c8ctl create pi --id MyProcess

入力変数を指定します。

c8ctl create pi --id MyProcess --variables '{"orderId": "ORD-123", "amount": 1500}'

--id は <bpmn:process id="...">（BPMN プロセス ID）に対応します。数値のプロセス定義キーではありません。

デプロイと開始を一度の手順で行います。

c8ctl run process.bpmn --variables '{"orderId": "ORD-123"}'

インスタンスの完了まで開始して待機します（テストやスモークチェックに便利です）。

c8ctl await pi --id MyProcess --variables '{"orderId": "ORD-123"}'

カスタムのリクエストタイムアウトを指定します。

c8ctl await pi --id MyProcess --requestTimeout 60000

長時間実行されるアクティビティには使用しないでください。 await pi はクラスターの開始・待機 REST エンドポイントを使用します。このエンドポイントは、単一のアクティビティがリクエストタイムアウトを超えて実行されるとタイムアウトします（LLM エージェント、応答の遅い HTTP 呼び出し、ユーザータスクなど）。タイムアウトした応答にはインスタンスキーが含まれないため、途中まで実行されたインスタンスを追跡できません。このようなプロセスには c8ctl create pi を使用し、終端状態になるまで c8ctl get pi <key> をポーリングしてください。または、await の失敗後に孤立したインスタンスを見つけるには、c8ctl search pi --state=ACTIVE を使用してください。

スクリプトでは、create pi を --json とともに実行し、返された key フィールド（プロセスインスタンスキー）を取得して、後続の操作（c8ctl get pi <key>、c8ctl cancel pi <key>、プロセスインスタンスキーによるインシデント検索）に使用します。

ウォッチモード（開発）

ローカル開発中に、ファイルの変更を検知して自動再デプロイします。

c8ctl watch ./my-project

.bpmn、.dmn、.form ファイルを監視し、保存時に再デプロイします。

プロセスインスタンスの確認

アクティブなインスタンスを一覧表示します。

c8ctl list pi

プロセス名で検索します（i プレフィックスは、大文字と小文字を区別しない部分一致を意味します）。

c8ctl search pi --iprocessDefinitionName="MyProcess"

変数を含むインスタンスの詳細を取得します。

c8ctl get pi <instanceKey> --variables

特定のインスタンスの変数値を出力します（切り詰めを避けるには --fullValue を使用します）。

c8ctl search variables --processInstanceKey=<key> --fullValue

プロセス定義のデプロイ済み BPMN XML を取得します。

c8ctl get pd <key> --xml

インシデントの解決

インシデントは、回復不能なエラー（FEEL エラー、変数の欠落、コネクターの失敗、ジョブのタイムアウトとリトライ超過など）が発生した際に、クラスターがインスタンスを一時停止するための仕組みです。解決する前に、必ず内容を確認してください。

最初の対応としてのトリアージ — ユーザーから「インスタンス X が停止している」と報告された場合、解決するか判断する前に、次の4つを順番に実行して状況を評価します。

PI=<instanceKey>
c8ctl get pi $PI                                              # state (ACTIVE = stuck on a step), processDefinitionId
c8ctl search inc --processInstanceKey=$PI                     # any incidents on this PI, with errorType
c8ctl search variables --processInstanceKey=$PI --fullValue   # variables at the failure point
c8ctl get inc <incidentKey> --json                            # full error message

通常、この4つを組み合わせることで、Operate を開かずに原因を特定できます。

アクティブなインシデントを一覧表示します。

c8ctl list inc
c8ctl search inc --state=ACTIVE

エラーメッセージで絞り込みます。

c8ctl search inc --ierrorMessage="Connection refused"

プロセスにインシデントが発生した場合のデバッグワークフロー：

1. インシデントを見つけて、エラーの種類とメッセージを確認します。

   c8ctl search inc --state=ACTIVE
   

2. 失敗した時点のインスタンス変数を確認します。

   c8ctl search variables --processInstanceKey=<key> --fullValue
   

3. 根本原因を特定します。 よくあるカテゴリは次のとおりです。

   • FEEL エラー（EXTRACT_VALUE_ERROR / CONDITION_ERROR）→ 式を修正するには camunda-feel を参照してください。ドット付き変数名によるシャドーイングや null 入力を確認してください。
   • ジョブワーカーが存在しない、またはタイムアウトしている → <zeebe:taskDefinition type="..."> が実行中のワーカーと一致することを確認してください。
   • コネクターの設定ミス → 要素テンプレートのバインディングを修正するには camunda-connectors を参照してください。
   • BPMN ロジックの不具合 → 修正して再デプロイするには camunda-bpmn を参照してください。

4. 根本原因となっている問題を修正します（BPMN の編集、コネクターの再設定、ワーカーの修正、または変数の修正）。

5. 失敗したステップを再試行するために、インシデントを解決します。

   c8ctl resolve inc <incidentKey>
   

根本原因を修正せずに解決すると、同じインシデントが再び発生します。必ず先に修正してください。

ユーザータスクの完了

保留中のユーザータスクを一覧表示します。

c8ctl list ut

出力変数を指定して完了します。

c8ctl complete ut <taskKey> --variables '{"approved": true, "comments": "Looks good"}'

変数キーは、フォームのコンポーネントの key 値と一致する必要があります（camunda-forms を参照してください）。余分なキーは無視されます。必須キーが不足していると、後続の処理を完了できません。

相関メッセージのパブリッシュ

インスタンス内で待機中のメッセージイベントを起動するメッセージをパブリッシュします。

c8ctl publish msg <messageName> --correlationKey=<key> --variables '{"status": "approved"}'

相関キーは、プロセスのメッセージサブスクリプション式から解決される値と一致する必要があります（通常は変数に対する FEEL 式です。例：=orderId）。

インスタンスのキャンセル

c8ctl cancel pi <instanceKey>

本番環境の監視ループ

継続的なプロセスのヘルスチェックには、この軽量なループを使用します。

1. アクティブなインシデントをスキャンする — コマンドはフラットな JSON リストを返します。使用するツールやシェルで、errorType / elementId によるグループ化やフィルタリングを行います。

   c8ctl search inc --state=ACTIVE --json --fields=key,errorType,errorMessage,elementId,processInstanceKey
   

2. 複数のインスタンスにわたって、elementId と類似する errorMessage の値が繰り返されていないか、フラットなリストを調べてインシデントが再発しているかを判断します。再発は、一時的なランタイムの不具合ではなく、プロセス／モデル／ワーカーの欠陥を示しています。

3. 少なくとも1つの失敗例について、変数とインスタンスの状態を関連付けて確認します。

   c8ctl get pi <instanceKey>
   c8ctl search variables --processInstanceKey=<instanceKey> --fullValue
   c8ctl get inc <incidentKey> --json
   

4. 根本原因に対する最小限の修正を適用してから、1つのインシデントを解決し、新しいインスタンスで同じ失敗が起きなくなったことを確認します。フラットなリストに該当タイプのアクティブなインシデントがなくなるまで、手順1から繰り返します。

（インシデント対応だけでなく）SLA とスループットの傾向を把握するには、このランブックをメトリクス監視ツール（Operate/Optimize のダッシュボード）と併用し、調査結果を BPMN の変更やワーカーの信頼性向上に反映してください。

スクリプト用 JSON 出力

呼び出しごとに --json を指定し、必要に応じて --fields で対象を絞り込みます。セッション全体の出力モードは切り替えないでください。理由については camunda-c8ctl を参照してください。

c8ctl list pi --json --fields=key,state,bpmnProcessId
c8ctl list pd --json --fields=key,bpmnProcessId,version
c8ctl get inc <key> --json

トラブルシューティング

デプロイに失敗する — まず c8ctl bpmn lint process.bpmn を実行します（camunda-bpmn を参照）。デプロイエラーのほとんどは、デプロイ前のリンターで検出できます。

プロセスが開始しない — プロセス ID がデプロイ済みの定義と一致していることを確認します（c8ctl list pd）。必須の入力変数も確認してください。

インスタンスがサービスタスクで停止する — そのタスクタイプに対応するワーカーが登録されていない、ワーカーがクラッシュした、または最大再試行回数を超えてジョブがタイムアウトした可能性があります。c8ctl list jobs --processInstanceKey=<key> を確認し、対応するタスクタイプのワーカープロセスが実行中であることを確認してください。

同じインシデントが繰り返し発生する — 修正せずに解決している状態です。毎回エラーメッセージを確認してください。内容が変わらない場合、根本原因は解消されていません。