nocobase-workflow-manage

目標

nb api workflow を通じて、NocoBase のワークフローをエンドツーエンドで管理します。

1. 認証済みの nb CLI が必要です。
2. 現在のタスクでサブコマンドを初めて使う前に、-h を一度実行します。
3. ワークフロー専用の CLI インターフェースのみを使用します。汎用 CRUD やソース編集で代用しないでください。

対象範囲

• ワークフローの確認、作成、更新、バージョン管理、コピー、有効化、診断。
• トリガーと順次実行されるノードチェーンの設定。
• ノードや分岐の移動、複製、テスト、削除。
• 実行履歴と失敗したジョブの確認。
• flowSurfaces を使ったワークフローに紐づく承認画面の作成。

対象外

• nb のインストールや認証設定。
• データモデルの設計。nocobase-data-modeling を使用してください。
• 通常のページ、タブ、ポップアップ、ルート。nocobase-ui-builder を使用してください。
• ワークフロー全体の削除。
• 承認スキーマの接続設定。
• 型、フィールド、キー、フィルター、評価関数を創作すること。

入力要件

環境とツール

• 認証または認可エラーが発生した場合は停止してください。
• expression については、対応する formula.js または math.js のリファレンスを読み込み、関数を創作しないでください。

フィルター作成の必須手順

ワークフローノード／トリガーの filter または condition、あるいはユーザー／担当者のクエリーオブジェクトを作成する前に、filter トピックで nocobase-utils スキルを読み込み、現在のタスクで Filter Condition Format を読んでください。自然言語による比較が明白に見える場合も必須です。相対リンクは正確なドキュメントの場所を示すだけであり、スキルの呼び出しに代わるものではありません。

1. 対象コレクションのフィールドメタデータを読み込み、末端フィールドのフロントエンドインターフェース／型を特定します。
2. そのフィールドグループで文書化されている許可リストからのみ演算子を選択します。
3. 日付フィールドの場合、「より前／未満」は $dateBefore、「より後／超過」は $dateAfter、「より前ではない／以上／以上」は $dateNotBefore、「より後ではない／以下／以下」は $dateNotAfter に対応させます。日付フィールドには $lt、$lte、$gt、$gte を使用しないでください。
4. 設定で文書化されているフィルター形式を維持し、変更前に最終的なフィールドと演算子の組み合わせを確認します。

商用プラグイン機能の必須確認

変更前に、必要なプラグインがインストールされ、有効になっていることを確認してください。

機能	プラグイン
承認と承認画面	@nocobase/plugin-workflow-approval
Webhook	@nocobase/plugin-workflow-webhook
サブフロー	@nocobase/plugin-workflow-subflow

利用できない場合は、前提条件を明示し、その手順を中止してください。要求された承認の動作を manual ノードで代替しないでください。商用プラグインの確認を参照してください。

必須の確認事項

• 未解決の作成時の選択、破壊的な操作、リスクの高い選択、または所有者の選択についてのみ質問します。確認は最大2ラウンド、各ラウンドにつき質問は3つまでです。
• 後から編集できる詳細の確度が70％以上であれば、そのまま進めます。変更後に確認してください。
• 変更前に、対象を一意に特定し、意図する最終状態を正確に確定する必要があります。
• どのコピー方式を意味するかはユーザーに尋ねないでください。以下の手順から判断し、変更前に選択した結果を伝えてください。

ワークフロー更新とコピー意図の判定

ユーザーは通常、技術的な改訂ではなく変更内容を説明します。望ましい結果に基づいて振り分けます。

意図	手がかり	振り分けと結果
既存のワークフローを変更する	ロジック、トリガー、条件、またはノードの更新・調整	nodes と versionStats を取得します。versionStats.executed > 0 の場合は、先に同じワークフローのリビジョンを作成します。それ以外の場合は、その場で編集します。独立したワークフローは作成しません。
新しいバージョンを作成する	新しいバージョン／リビジョン、履歴の保持、または後継バージョンを明示	同じ key でリビジョンを作成します。バージョンの実行数はゼロから始まり、履歴とキー単位の集計統計は保持されます。
ワークフローエンティティをコピーする	コピー／クローン／名前を付けて保存、別のプロセス／テンプレート、名前を変更したコピー、統計のリセット、または単に「このワークフローをコピー」	新しい key を持つ独立したワークフローを作成します。実行数と履歴は空の状態から始まります。

優先順位：バージョンの継続性を明示 → リビジョン；別個のアイデンティティを明示 → 独立したコピー；具体的な動作変更 → 更新；単にワークフローのコピーを指示 → 独立したコピー。

リビジョンでは、次の呼び出しを厳密に使用します。

# Same workflow, new version
nb api workflow workflows revision \
  --filter-by-tk <source-id> \
  --filter '{"key":"<source-key>"}'

# Independent workflow
nb api workflow workflows revision \
  --filter-by-tk <source-id>

• 同じワークフローモードでは、正確なトップレベルの制御オブジェクト {"key":"..."} が必要です。これを $and／$or の中に入れたり、本文に記述したり、空のフィルターを使用したりしないでください。
• 独立したコピーでは filter を省略します。
• 以降の変更を行う前に、変更結果を読み戻します。リビジョンでは id が新しくなり、key は変わりません。独立したコピーでは両方が異なります。
• CLI は filter を単一の JSON クエリオブジェクトとして送信します。リポジトリがモードを切り替えるのは、filter.key が直接指定されている場合のみです。

コレクション解決の判定

必要な collection が不明確な場合は、次の手順に従います。

1. nocobase-data-modeling を使用して、既存のコレクションとフィールドを確認します。
2. 確信度が 70％以上の一致候補を使用します。
3. それ以外の場合は、コレクションを特定するか作成するようユーザーに尋ねます。

これは、コレクションに紐づくトリガー、操作、スケジュール、ノードに適用されます。ワークフローの規約を参照してください。

リファレンスの読み込みマップ

• バージョン操作とコピー操作：workflows CLI
• HTTP トランスポート：workflows HTTP API
• キー、バージョン、統計：workflow model
• 作成：トリガー、ノード、規約
• ノード／トリガーのフィルター、条件、担当者クエリを使用する場合：トピック filter を指定して nocobase-utils を読み込み、演算子を選ぶ前にフィルター条件の形式を確認します
• 承認 UI：承認 UI のインデックスとサーフェスの制約

最終的なコマンド一覧

• ワークフロー：workflows list|get|create|update|revision|sync|execute
• ノード：workflows nodes create；flow-nodes get|update|destroy|destroy-branch|move|duplicate|test
• 診断：executions list|get；jobs list|get|resume
• 承認サーフェス：flowSurfaces get|catalog|applyApprovalBlueprint|addBlock|addField|addAction|compose|configure|setLayout

フラグについては CLI インデックスを、基盤となるリクエスト形式についてのみ HTTP API インデックスを使用してください。

承認 UI エントリ

• 承認画面は approvalUid または taskCardUid に紐付けられており、通常のページではありません。
• 起票者 UI には ApplyFormModel が必要です。承認者 UI には ApprovalDetailsModel と ProcessFormModel の両方が必要です。
• ライブカタログが返すアクションとブロックのみを使用してください。照合済みのノードアクション設定を手動で変更しないでください。
• 初回セットアップまたは置き換えには applyApprovalBlueprint を使用してください。
• ローカライズされた操作を行う前に、紐付けられたルートを解決してください。
• タスクカードでは fields + layout がサポートされています。レイアウトのみを編集する場合は setLayout を使用してください。
• フィールドコンポーネントのオプションは catalog.node.configureOptions.fieldComponent.enum から読み取ってください。
• 作成を始める前に承認 UI インデックスを読み込んでください。ペイロードのルールについては画面の制約を読み込んでください。

安全ゲート

1. ワークフローは無効の状態で作成し、有効化する前に確認を求めてください。
2. 編集またはコピーの前に更新・コピーゲートを適用してください。
3. すべての変更操作または破壊的操作には、具体的な対象を指定してください。
4. ノードは順番に作成し、upstreamId で接続してください。
5. 保存されるすべてのノード／トリガーフィルターにフィルター作成ゲートを適用してください。ワークフローデータ／クエリのフィルターは $and または $or で囲んでください。改訂管理についてはインテントゲートを参照してください。
6. ノードの結果を参照する際は、数値の id ではなく、返されたノードの key を使用してください。
7. 下流で使用する前に、json-variable-mapping または json-query で未加工の JSON をモデル化してください。
8. すべての変更操作の結果を読み返してください。
9. 手動実行の前に確認を求めてください。

ワークフロー

計画フェーズ

インテント、トリガー、ノードチェーン、同期モード、コレクション、フィルター、マッピング、変数、未加工の JSON のモデル化を確認してください。保存されるフィルターが必要な場合は、トピック filter を指定して nocobase-utils を読み込み、フィルターリファレンスを確認し、演算子を作成する前に各末端フィールドの型を特定してください。計画と、履歴／統計への影響を明示してください。

承認 UI では、リクエストを画面全体のセットアップ／置き換えまたは局所的な編集に分類してから、承認 UI リファレンスを読み込んでください。

新しいワークフローの作成

1. コレクションを特定します。
2. enabled: false で作成します。
3. トリガーを設定します。
4. 安全ゲートに従ってノードチェーンを構築します。
5. 検証チェックリストを完了します。

既存のワークフローの編集

1. nodes と versionStats を含めてワークフローを取得します。
2. 更新・コピーゲートを適用します。
3. 解決済みの編集可能な id のみを変更します。
4. 検証チェックリストを完了します。

失敗した実行の診断

1. workflowId で実行を新しい順に一覧表示します。
2. ジョブ、ワークフロー、ノードを含めて実行を取得します。最初はジョブの結果を省略します。
3. ステータスが -1（失敗）、-2（エラー）、または -3（中断）のものを見つけます。
4. 失敗したジョブを取得して result を確認します。
5. 設定を修正してから、安全ゲートに従ってください。

エラー処理

• 400/422：報告された型、フィールド、またはリンクのエラーを修正してから再試行します。
• 認証エラー：停止し、アクセスの復旧を依頼します。
• ノードの作成失敗：下流ノードを作成する前に、問題を修正するか失敗したノードを削除します。
• 改訂エラー：再試行する前に状態を再取得します。

検証チェックリスト

以下を確認します。

1. ワークフローの種類、タイトル、同期モード、有効状態。
2. トリガーの設定。
3. ノード数、順序、種類、設定、upstreamId チェーン。
4. 必須の変更フィルターが空でないこと。
5. 改訂／コピーの id と key が選択したモードに一致していること。
6. 承認ルートと画面の読み戻し結果が、意図したルートと一致していること。
7. 下流で使用する前に、未加工の JSON がモデル化されていること。
8. 必須の商用プラグインが有効であること。
9. 返された変更後の状態が、要求した結果と一致していること。
10. 保存されるすべてのフィルターについて、フィールド／演算子の組み合わせが末端フィールドのフロントエンド演算子グループに照らして確認されていること。日付フィールドに数値比較演算子が含まれていないこと。

プラグインのバージョン管理に関するリビジョンルール

• 毎回 nocobase-revision を読み込みます。利用できない場合は、このセクションを無視し、そのことについて何も開示しないでください。
• このスキルで nb revision create が利用可能であると確認されるまで、リビジョン情報を開示しないでください。
• 利用可能な場合は、最終回答の直前にリビジョンを作成するかどうかを一度判断し、作成したリビジョン、または作成しなかった具体的な理由を報告してください。

参考資料

• 商用プラグインのゲート
• 承認 UI の索引および表示面の制約
• ワークフローモデルおよびワークフローのフィールド
• 規約
• CLIおよびHTTP API
• トリガーおよびノード
• フィルター形式および評価器
• データモデリングスキル
• 公式ワークフローハンドブックおよびリビジョンガイド [確認済み：2026-04-09]