uipath-maestro-bpmn

推論の予算

• ステップの難易度に合わせて推論し、まず行動することを優先します。機械的な作業、入出力、形式に関するステップでは、提供されたスクリプトで対応できるなら実行し、やり直して考えないでください。
• スクリプトでは判断できない、本当に難しい判断に限って、深く長い推論を行います。

作業スタイル

• まず理解してから決める。 このスキルの SKILL.md を読み、実行に移る前に付属スクリプトの内容を理解します。そのうえで、スクリプトが実際に行う処理に基づき、変更せずに実行する、適合するように変更する、補完用のスクリプトを追加で作成するなど、適切な計画を立てます。推測で決めないでください。
• 最初に全体の手順を計画してから、まとめて実行する。 実行前に手順全体を整理し、独立したステップは1回のターンにまとめ、ターンごとに逐次実行するのではなく、可能な限り少ないターン数で計画全体をパイプライン化します。
• 入力の確認は1回だけ。 ファイルの構造（シート、列、ページ、フォーム項目、キーなど）を把握するためにダンプする際は、1回だけ行います。できればファイルに出力してから grep してください。同じファイルを項目ごとに再度開いたり、複数のライブラリで試したりしないでください。例外は画像ソースです。コンテキストで見えなくなった場合は、画像を使った作成に関する説明に従って、必要に応じて再度確認してください。
• 作業を繰り返さない。 入力と関連する状態に変更がない場合、コマンドを再実行したり、すでにコンテキストにある変更されていないファイル、スクリプト、SKILL.md を読み直したりしないでください。ツールやコマンドでファイルが変更された可能性がある場合は、内容を再確認してから使用してください。
• コードは一度書いて再利用する。 ステップでコードが必要な場合は、パスやパラメーターを CLI 引数にした小さなスクリプトを一度作成して呼び出します。ターンごとに似た Python コードをインラインで貼り付けないでください。簡潔にし、コメント見出しや説明文は加えないでください。
• 出力は小さく保つ。 大量のツール結果や出力をコンテキストに含めず、ファイルに書き出してからツールで確認します。ツールを利用できない場合は、自分でスクリプトを作成してファイルを確認します。行が存在するかどうかを判断する場合は、切り詰めずに（head、sed -n は使わず）、フィールドで CLI JSON をフィルタリングします（jq select）。
• 不要なことはしない。 すぐに必要なものでない限り、ツールを呼び出したり、ファイルを読んだり、結果をコンテキストに含めたりしないでください。

UiPath Maestro BPMN

UiPath Maestro（プロセスオーケストレーション）の .bpmn プロジェクトについて、作成、検証、パッケージ化、運用、診断を行います。登録済みノードの作成はレジストリ主導です。それらの実行ペイロードは、レジストリから提供されるテンプレートを使用します。ノードをまとめる構造的な BPMN と、シリアライザーが管理するスキャフォールドメタデータ（プロセスのスキャフォールド、変数、バインディング、エントリーポイント、シーケンスフロー、ゲートウェイ、イベント、境界イベント、コンテナー、マルチインスタンスマーカー、図）は、仕様およびキャンバスの契約に従って作成します。パッケージ化、運用（アップロード、公開、実行）、診断は UiPath CLI を通じて行い、以下の機能リファレンスで説明します。

使用する場面

• 説明、またはプロセスの画像（スケッチ、ホワイトボード、付箋の写真、別の図のスクリーンショット）から Maestro .bpmn を作成する。
• .bpmn の構造（ゲートウェイ、イベント、境界イベント、サブプロセス、コールアクティビティ、マルチインスタンスループ、シーケンスフローの条件、変数）を編集する。
• UiPath 拡張ノード（RPA ジョブ、エージェント、HITL、キュー、ビジネスルール、API ワークフロー、Integration Service コネクター、内部メッセージ、タイマー）を追加する。
• インポート前に、キャンバスのルールに照らして .bpmn を検証する。
• プロジェクトをパッケージ化、アップロード、公開、実行し、ジョブやインスタンスを管理する。
• 失敗した実行や、正常に動作しない実行を診断する。

既存の .bpmn の編集（作成していない部分を保持する）

このスキルでは既存ファイルを編集できます。編集によって Patterns にある図形を挿入する場合は、そのガイドに従ってください。実行中の プロセスにパターンを挿入するのは通常の編集であり、図形を省略する理由にはなりません。最小限の 編集を行い、自分が作成していない内容を保持してください。不明な uipath:* 要素、uipath:migrationVersion、 タグ、インポート済みの Integration Service ペイロード、安定した要素 ID が対象です。ファイル全体を 再生成したり、このスキルが認識しない拡張データを削除したりしないでください — 保持のみを行う構造（ references/structural-bpmn.md のブロックリストを参照）は往復処理で 変更せずに保持します。既存ノードをこのスキルの標準テンプレートに正規化してはいけません。 編集対象外の要素に不足している属性（例：既存の uipath:input に type="json" target="bodyField"）を 追加しないでください — 未変更の隣接ノードでは、配線（bpmn:incoming／bpmn:outgoing）のみ変更できます。 例外：ペイロードに type 属性がある、または <bpmn:extensionElements> の外にある場合、 あるいは Orchestrator.StartAgentJob の型バージョンが v2 以外で、releaseKey または folderId に値がない場合は、validate エラーになります。そのようなペイロードはルール 6 に従って書き換え、 それぞれを概要に記載してください。

既存の ScriptTask では、マッピングの識別子と uipath:scriptVersion を保持し、新規ノードの作成要件と異なるというだけで、動作しているブラウンフィールドノードを 正規化しないでください。移行には明示的な確認が必要です — references/structural-bpmn.md を参照してください。

.flow JSON には uipath-maestro-flow を、XAML／コード化されたワークフローには uipath-rpa を、Python エージェントには uipath-agents を、Case プランには uipath-maestro-case を使用してください。

モデル

有効な Maestro .bpmn は、次の 2 つの部分で構成されます。

1. レジストリに登録されたノードのペイロード — レジストリが管理します。 登録された各ノードの 実行 XML（uipath:activity／uipath:event／uipath:mapping、その context、input、output、bindingInfo）は、 uip maestro bpmn registry get <type> の xmlTemplate から取得します。レジストリが管理するノードのペイロードを、文章から手作業で作成してはいけません。
2. 構造的な BPMN とスキャフォールドのメタデータ — 仕様／キャンバスが管理します。 レジストリからは <bpmn:definitions>／<bpmn:process>、シーケンスフロー、ゲートウェイの 条件／デフォルト、イベント定義のペイロード、境界イベントの属性、サブプロセス／ループの構造、 ダイアグラムは出力されません。uipath:variables、uipath:bindings、 uipath:entryPointId、uipath:migrationVersion などのシリアライザーが管理するスキャフォールド拡張も、 ノードテンプレートではなく、この仕様に基づきます。これらは、 レジストリ仕様、CLI スキャフォールド、キャンバスシリアライザーを根拠とする references/structural-bpmn.md に従って作成してください。

パターン

新しいプロセスの構築や、すでに稼働しているプロセスの拡張に使える、繰り返し現れる7つのプロセス形状です。各ガイドでは、ノード、接続、ゲートウェイ条件、変数で構成される実例のトポロジーと、その理由を説明します。同じリクエストでも、検証に合格するトポロジーは多数あります。ここで紹介するのは、実績のある形であり、仕様ではありません。プロセスの要件に合わせて、ステップを追加したり、分岐を削除したり、数を変えたりしてください。各ガイドの「有効な理由」では、その形を成り立たせている要素を挙げています。これらを変更すれば別のものを構築することになるため、その旨を明記してください。プロセスで実際に使うパターンごとにガイドを読みます。単純なプロセスなら1つ、組み合わせたプロセスなら複数です。構築しないパターンのガイドを読む必要はありません。

各ガイドの形状表では、各ノードを Entry（稼働中のプロセスに挿入する場合は省略）、Mechanism（変更するとパターンが変わる）、または Placeholder（バインドするか、プロセスですでに実行されている場合は省略）として示します。表に記載された要素を作成してください。ステップ1で解決されなかった対象ステップの Placeholder は、レジストリのペイロードを持ち、識別用のスロットをパブリックプレースホルダーのままにした要素にしてください。処理を担う要素の代わりに、単なる bpmn:task を置いてはいけません。

パターン	使用する場面	ガイド
ai-decision-review	AI が1回呼び出され、その結果に基づいて処理するか、人間が確認します	ai-decision-review-guide.md
approval-chain	申請に複数人の承認が必要です	approval-chain-guide.md
smart-triage	受信した作業をカテゴリに分け、それぞれを別の場所で処理します	smart-triage-guide.md
external-wait	SLA に基づき、プロセスが外部の関係者からの応答を待ちます	external-wait-guide.md
high-volume-batch	多数の独立した項目を1回の実行で処理します	high-volume-batch-guide.md
failure-escalation	未処理の障害が気づかれないまま放置されないようにします	failure-escalation-guide.md
queue-distribution	Orchestrator キューを使って、複数のランタイム間で作業を引き継ぎます	queue-distribution-guide.md

パターンを使う必要がない場合：短い直線的なプロセス、単一ノード、またはこれらの形状を導入しない変更には、パターンを使わないでください。パターンは、必要のない作業に後付けするラッパーではありません。

1つのプロセスで複数のパターンを使いますか？まず references/patterns/composing-guide.md を読んでください。どのパターンが開始イベントを保持するか、残りを結合する4つの方法、ネスト境界を越えて変数を渡す方法、エンジンによって配置が制約される2つの要素について説明しています。パターンを1つだけ使う場合は、そのパターンのガイドだけで十分です。

画像からの作成

プロセスの元が画像の場合、作業は文字起こしです。画像内のすべての項目がノードになり、表示されているすべてのコネクターがフローになります。画像に「着想を得た」もっともらしいプロセスは、文字起こしではありません。よくある失敗は、要約しながら項目を削除したり統合したりして、その要約をもとに作成することです。

1. 解釈する前に項目を洗い出します。 トポロジーを提案する前に、表示されている項目をすべて書き出します。正確な文言、色や形、おおよその位置を記録してください。次に、表示されているすべてのコネクターについて、始点 → 終点、ラベル、および確実か曖昧かを列挙します。読めない項目や取り消し線が引かれた項目は、推測したり省略したりせず、印を付けてください。このリストはプロジェクトフォルダー外のノートファイルに保存します。
2. 要約ではなく、項目の一覧を確認します。 ルール 4 に基づいて確認する構造には、一覧にあるすべてのノードとフローを含める必要があります。簡略化したトポロジーや「解釈した」トポロジーを推奨案として提示してはいけません。曖昧な点ごとに個別に質問し、画像に表示されていない追加要素（開始／終了イベント、キャンバスで必要となるマージゲートウェイ、暗示されたリンクの解釈など）についても、それぞれ個別に質問してください。
3. 1 対 1 で文字起こしします。 項目ごとに 1 つのノードを作成し、画像内の文言と「はい／いいえ」の分岐ラベルを維持します。キャンバスで必要な場合に限り技術的な補助要素を追加し、最終報告で追加内容をそれぞれ明記します。
4. 画像を常に確認できる状態にします。 以前のターンの画像は、コンテキストから消えることがあります。特にユーザーが新しいメッセージを送った後、ホストが画像をテキストのプレースホルダーに置き換えることがあります。忠実性が求められる作業を行う前に、結果が一致しないとユーザーが伝えた場合も含め、画像を実際に確認できるかを確かめてください。確認できない場合は、ファイルパス（ホストが提供した添付ファイルのパス）から読み直します。それでも確認できない場合は、ユーザーに再添付を依頼してください。画像の記憶、以前の要約、サブエージェントによるテキストの説明をもとに再作成してはいけません。サブエージェントが画像を文字起こしした場合は、編集する前に自分で画像と照合してください。
5. 完了前に忠実性を検証します。 validate が成功した後、画像をもう一度確認し、BPMN とノードごと、フローごとに照合します。残っている不一致があれば、完了とするのではなく報告してください。検証で証明できるのはファイルの構造的な妥当性であり、画像との一致ではありません。

ワークフロー

6 つのステップを手早く進めますが、ユーザーの依頼に合わせて進行方法を調整してください。作成前の調査、レジストリの生 JSON／証拠の保存、または「まだ作成しない」という依頼は、最終的に BPMN を作成すると記載されていても、調査のみの依頼として扱います。その場合は、ただちに registry-evidence/ を作成し、registry pull --output json、registry list --output json または registry search ... --output json、および依頼されたタイプごとに registry get <type> --output json を実行して保存します。詳細な作成リファレンスを読んだり、プロジェクトのひな形を作成したりしてはいけません。作成依頼の場合は早めに作成に取りかかり、執筆前にすべてのリファレンスを読まないでください。対象の構造に進んだときに、その構造を扱う箇所だけを読みます。references/structural-bpmn.md は、すべてのアンカーを示すセクション索引から始まります。必要なテンプレートを入手したら、さらに詳しく調べる前に最初の完全なドラフトを書きます。

レジストリの証拠のみを扱うタスクでは、references/registry-workflow.md のコマンド先行の手順に従ってください。

1. 検出します。 uip maestro bpmn registry pull を 1 回だけ実行します（セッション中はキャッシュされるため、再取得しないでください）。続いて list／search で意図を拡張機能の種類に対応付けます。稼働中の接続を確認するには uip is connections list --all-folders を実行します（必ず --all-folders を指定してください。フォルダーを限定した一覧では、接続が気付かないうちに欠落します）。識別子を捏造してはいけません。Rule 4 に該当する場合に限って確認し、それ以外は判断してください。各コネクターノードは、そのコネクターの Enabled 接続にバインドします。タスクで指定されたフォルダー内の接続を選び、なければ IsDefault が Yes の接続、さらにそれもなければ最初の接続を選びます。uip is connections ping <id> --output json で確認し（Data.Status が Enabled である必要があります。一覧の State はキャッシュ値です）、そうでなければ次の候補に進みます。所有者が別の人でも、スキップする理由にはなりません。Rule 4 の仮定として、バインドした各接続の Name、Owner、Folder を明記します（Id は記載しないでください）。プレースホルダーを使えるのは、ユーザーがドラフト、引き継ぎ、またはプレースホルダー、合成値、公開しても安全な値、サニタイズ済みの値を求めた場合か、Enabled と応答する候補がない場合に限ります。 references/registry-workflow.md を参照してください。

2. テンプレートを取得します。 選択したレジストリ管理対象ノードごとにのみ uip maestro bpmn registry get <type> --output json を実行します。選択したすべてのテンプレートを、コマンドごとに別のターンで取得するのではなく、1 回の Bash 呼び出しで取得してください。シェルの往復ごとにモデルのターンが消費され、コマンドを何十回も実行すると、作成を終える前に実行時間の上限に達してしまいます。 for t in TypeA TypeB TypeC; do uip maestro bpmn registry get "$t" --output json; done Intsvc.* コネクターノードには --connection-id／--object-name を指定して詳細を追加します。--object-name は references/registry-workflow.md の表から選んでください。コネクターは各操作で複数のオブジェクトを公開しますが、describe はその優先順位を示しません。レジストリが管理していない構造上の不足要素（シーケンスフロー、ゲートウェイ、イベント、境界イベント、マルチインスタンス／ループのマーカー、errorMapping／リトライ構造、ダイアグラム）に対して registry get を呼び出さないでください。貼り付ける bpmn: タグは、開始タグと終了タグの両方で、bpmn: の直後の最初の文字を小文字にします。<bpmn:UserTask> → <bpmn:userTask>、<bpmn:ServiceTask> → <bpmn:serviceTask> のようにします。ルール 6 と 18 に従う場合を除き、uipath:* のペイロードはそのまま維持してください。 BPMN.ScriptTask はレジストリ検索キーですが、新しいノードは <uipath:type value="BPMN.Variables" version="v1" /> としてシリアライズされます。検索キーを使ってはいけません。ローカル検証では古いディスクリミネーターも受け入れられるため、validate が成功しても、その対応付けが正しいとは限りません。互換性フォールバックとその適用範囲については、references/structural-bpmn.md#script-tasks--jint-authoring-contract を参照してください。

3. 組み立てます。 references/structural-bpmn.md にある完全な最小ファイルと、各ノードの xmlTemplate を基に直接作成します（プレースホルダーのみを埋めてください）。この骨組みには、安定した手動のエントリーポイント、構造タスク 1 つ、完全な DI が含まれています。タスクのフィクスチャ、生成済みパッケージファイル、または node_modules 内にインストールされたパッケージバンドルから、作成パターンをリバースエンジニアリングしてはいけません。このような調査が、作成の時間切れを招く最大の原因です。 プロセスに必要な構造要素（追加のゲートウェイ、イベント、境界イベント、コンテナー、マルチインスタンスマーカー、式／エラーマッピング、リトライ属性）のみを追加します。ダイアグラムはステップ 4 で追加してください。ソースがまだ変更されている間は、bpmndi:* を手書きしないでください。新しいローカルプロジェクトでは、uip maestro bpmn init <ProjectName> --output json でサポート対象のスキャフォールドを初期化し、返された Data.Path で編集して、生成されたメタデータを維持します。パッケージ化や運用をユーザーが求めていないソースのみのドラフトでは、--skip-solution-registration を指定して、*Solution/ ラッパーや .uipx が作成されないようにします。init に渡すのはパスではなくプロジェクト名です。また、現在のディレクトリ配下に書き込みます。このフラグを指定した場合は ./<ProjectName>/ に、指定しない場合は既存のソリューション内の ./<ProjectName>Solution/<ProjectName>/ に作成されます。 ユーザーがソリューション名を指定した場合（「同じ名前のソリューション」は <ProjectName>Solution ではなく <ProjectName> です）、ソリューションを作成し、その中から init を実行します。

   uip solution init <SolutionName> --output json
   cd <SolutionName> && uip maestro bpmn init <ProjectName> --output json
   

   応答に Data.AutoCreatedSolution が含まれている場合は、init がソリューションの外で実行されています。ソリューションの中から再実行し、誤って作成されたディレクトリを報告してください。 ユーザーが指定したパスにプロジェクトを配置するには、親ディレクトリを mkdir -p で作成し、末端のディレクトリ名を名前として、その場所で init を実行します。または --skip-solution-registration を渡すか、 先に親ディレクトリをソリューションにします。デフォルトの init は、 指定されたパスにはない <ProjectName>Solution/ 階層を挿入するためです。 編集前に Data.Path が指定されたパスと一致することを確認してください。 init のスキャフォールドでは xsi 名前空間が宣言されません。 xsi:type 属性を書き込む前に、bpmn:definitions に xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" を追加してください。 references/shared/local-metadata-regeneration-guide.mdを参照してください。 実行可能な BPMN／start-event のパスは、小文字の operate.json.main に 記述します。project.uiproj.main には記述しません。 ドラフト版または保持専用のケース管理バリエーションを追加する場合は、 合成コンテンツを含む実際の小文字の <uipath:caseManagement version="v1">...</uipath:caseManagement> ペイロードを、保持専用の別の拡張として含めてください。ユーザーが ケース管理コントラクトのバリエーションの保持を求めている場合、 Orchestrator.StartCaseMgmtProcess* の型付きアクティビティシェルを そのペイロードの代用として扱わないでください。 汎用の未対応 uipath:Activity の保持を求められた場合は、実際の大文字の 要素 <uipath:Activity version="v1">...</uipath:Activity> を記述してください。 <uipath:activity><uipath:type value="uipath:Activity" ... /> は記述しないでください。 これは小文字の型付きシェルであり、保持専用の汎用ペイロードではありません。 XML 属性値に公開しても安全なプレースホルダーを書き込む場合は、山括弧を XML エスケープしてください。属性内では <TENANT_URL>、<FOLDER_KEY>、<CONNECTION_NAME> を 使用します。エスケープされていない山括弧を属性内に含めると BPMN が 整形式でなくなるため、<PLACEHOLDER> の生テキストを安全に使えるのは 要素テキストまたは CDATA 内だけです。 Actions.HITL ユーザータスクの結果に基づいてルーティングする場合、 排他的ゲートウェイからのシーケンスフロー条件では、HITL テンプレートの <uipath:output ... var="..."> でバインドされた変数を正確に参照してください （例：=vars.Var_HitlResult == "approve"）。コピーまたは派生した スクリプト変数だけを参照してはいけません。 inputTarget が body の Intsvc.* アクティビティ （Intsvc.ActivityExecution とその非同期、エージェント、ワークフローの各バリエーション） については、以下のルールがテンプレートの InputNotes、DiscoveryNotes、 ContextFieldNotes に優先します。

   • ボディは 1 つ。 リクエストオブジェクト全体を CDATA に含める <uipath:input name="body" type="json" target="body"> は、必ず 1 つだけにします。フィールドごとに入力を分けたり、 配列をそのまま渡したりしてはいけません。ドット区切りの名前はネストします （fields.project.key → {"fields":{"project":{"key":…}}}）。 users[*] は users 内の配列です（{"users":["U1","U2"]}）。 ボディの形状を参照してください。
   • Parameters は必須です。 Required: true の各エントリー （Slack の send_as）は、それぞれ独立した uipath:input とし、 target にはその Type を設定します。</uipath:context> の後に置き、 リクエストの値を設定します。値がない場合は DefaultValue を使います。 パラメーターを参照してください。
   • operation（Intsvc.ActivityExecution のみ）には、記述されている Operation.Name（Create、List、Retrieve、Update、Delete、 Replace）を設定します。アクティビティの Name は使いません。
   • Data Service のファイルには、 UploadFileToRecordField、DownloadFileFromRecordField、 DeleteFileFromRecordField を使います。uip is resources list に 表示される V2 オブジェクトは使いません。 オブジェクトの選択を参照してください。
   • folderKey（Intsvc.ActivityExecution のみ）。接続をバインドする すべてのノードで、テンプレートの folderKey コンテキスト入力を =bindings.<folderBindingId> のまま維持し、フォルダバインディングも 含めてください。これがないと、実行時に 102010 Value cannot be null (Parameter 'Folder') エラーが発生します。 バインディングを参照してください。
   • 値。 Reference フィールドには、検索した ID を指定します（ルール 2）。 先頭に = がないボディ値はリテラルです。"=vars.<id>" のように記述し、 テキストと変数を組み合わせる場合は 1 つの =js: 式にします （"=js:'Severity: ' + vars.Var_Severity"）。 ユーザーが求めた Integration Service のドラフトまたは引き継ぎ境界の場合 （検証だけを求めるリクエストは該当しません）、.bpmn とノートファイルのみを 出力してください。生成される 4 つのパッケージファイルは作成しないでください （ルール 16）。それらを作成すると、このタスクで検証する境界に違反します。 ノード自体は引き続き作成します。レジストリの Intsvc.* テンプレートを貼り付け、 テンプレートが宣言するシェルを維持してください。アクティビティには uipath:activity、Intsvc.WaitForEvent と Intsvc.EventTrigger には uipath:event（ルール 6）を使い、コンテキストと出力も含めて、 リソース ID のスロットにはエスケープ済みの公開プレースホルダーを設定します。 イベントコンテキストでは接続を connectionId として参照し、アクティビティでは connection として参照します。シェルを持たないホスト要素は、たとえば uipath:activity のない単独の bpmn:sendTask のように、ドラフトではなく ノードの欠落です。解決済みの値だけが CLI の管理対象です。 references/registry-workflow.mdを参照してください。 Integration Service のドラフトノートでは、CLI 管理対象の阻害要因をすべて 具体的に列挙してください。正確な語句 connection binding に加え、動的スキーマ、 生成された出力、bindings_v2.json、パッケージメタデータも含めます。 「connection and process binding」のような曖昧な表現は、CLI が提供すべき 具体的な成果物を隠してしまうため避けてください。 start event の ID を変更する編集や、エントリーポイントを追加または削除する編集の 後には、必ず uip maestro bpmn refresh <project-path> を実行してください。 パッケージ化や運用のときだけではありません。トリガー開始のドラフト （下記）は例外です。最初に図を配置してください（手順 4）。 refresh は書き込み前に検証するため、追加したばかりのノードが MISSING_DI_SHAPE で失敗します。operate.json と entry-points.json は 一度生成されるとソースの編集には追従しません。そのため手順 5 のバリデーターは 不一致で失敗します。entry-points.json references start event "Event_start" via filePath, but no <bpmn:startEvent id="Event_start"> exists。上記のスケルトンから作成すると、 イニシャライザーの Event_start の名前が変更されるため、ソースのみのドラフトでも この処理が必要です。出力は記載どおりに維持してください。この形状が pack の 消費するコントラクトです。 refresh を実行するには init によって生成されたプロジェクトが必要です。 project.uiproj がない場合は Required file is missing / RetryWillNotFix で失敗します。このリポジトリの編集フィクスチャのように .bpmn だけがある場合は、先に 2 つのキーを持つ project.uiproj を作成します — { "Name": "<ProjectName>", "ProjectType": "ProcessOrchestration" } — その後 refresh を実行すると、 残りのファイルが書き込まれます。CLI が使えない場合に限り、 references/shared/local-metadata-regeneration-guide.md にある同等の手動作成形状を使用してください。CLI のスキャフォールドメタデータの 形状を合成ローカルプロジェクトにコピーしないでください。ルートにあるすべての 手動 start event には、その extensionElements 内に <uipath:entryPointId value="<uuid>" /> 子要素が必要です。これがないと、 refresh は空のエントリーポイント一覧を書き込む代わりに、プロジェクト全体を RetryWillNotFix で失敗させます。リクエストでトリガーを開始点に指定し、 パッケージ対応、アップロード、デバッグ、公開、デプロイの成果物を求めていない場合は、 トリガー開始のドラフトです。イニシャライザーの Event_start をそのまま トリガーに変更し、ID と uipath:entryPointId 子要素を維持してください。 2 つ目の start は追加せず、接続のバインド後であっても、手動 start がないと refresh が失敗するため実行しません。entry-points.json は有効なままです。 これらの成果物のいずれかが求められた場合は、そのドラフトに後から追加する場合も含め、 手動の Event_start を維持し、トリガーには独自の start ID を設定し、 ゲートウェイに従って両方を接続し、 refresh を実行します。繰り返しタイマーには timeDuration ではなく、 R/ 反復を使う timeCycle（R/P1D）を指定します。 refresh を実行せず、entry-points.json を編集または削除して古いエントリーの エラーを解消すると、validate と pack は通りますが、空の bindings_v2.json が含まれたままになります。公開入力と出力には明示的なランタイム ブリッジを設定し、1 つの結果を返すルートは単一の完了 EndEvent に集約してください。 2 層のコントラクトについては references/structural-bpmn.mdを参照してください。

4. 図を配置します。 最後のソース編集の後、validate、refresh、 pack のいずれかを実行する前に配置します。これには、手順 3 で呼び出す refresh も含まれます。

   uip maestro bpmn format <file.bpmn>
   

   ファイルの bpmndi:BPMNDiagram をその場で上書きするため、キャンバスではプロセスが原点に積み重なるのではなく、配置された状態で表示されます。ソースのみのドラフトを含め、すべての成果物に適用してください。また、これは見た目を整えるだけの処理ではなく、次の2つの手順を実行するための必須条件です。BPMNShape のないノードや BPMNEdge のないフローがあると validate は MISSING_DI_SHAPE／MISSING_DI_EDGE で失敗し、ダイアグラムがまったくない場合は BPMN_PARSE_ERROR で失敗します。さらに、refresh は書き込み前に検証するため、同じ理由で失敗します。ソースを再編集するとレイアウトは古くなるため、再検証の前にこの手順をもう一度実行してください。format が unknown command を報告する場合は、CLI を更新してください（references/cli-conventions.md を参照）。アップグレードできない場合は、references/structural-bpmn.md にあるフォールバック用の DI 構造を手作業で作成してください。

5. 検証します。 まず整形式かどうかを確認します。validate は寛容なパーサーでトークン化し、名前空間プレフィックスが未バインドの XML に対しても Valid を報告するため、ここでの ParseError は、ほかの作業に進む前に修正すべきソースの不備です。次に CLI バリデーターを実行します。これはオフラインで、PO.Frontend のキャンバスルール一式（構造ルールに加え、変数、メソッド呼び出し、入力型、イベントオブジェクトのチェック）と、デプロイ準備状況のチェックを実行します。

   python3 -c "import sys, xml.etree.ElementTree as ET; ET.parse(sys.argv[1])" <file.bpmn> &&
     ! grep -nE '</?bpmn:[A-Z]' <file.bpmn> &&
     uip maestro bpmn validate <file.bpmn> --output json
   

   validate はタグの大文字・小文字を区別しません。grep が出力した行は、小文字にすべきタグです（手順 2）。

   終了コード 0 = 有効です。終了コード 1 = 解析エラー、grep の検出、または validate の失敗です。各問題の重大度は、Found N error(s) ヘッダーではなく、[error]／[warning] タグで判断してください。このヘッダーはエラーを数える一方、その下の一覧には警告も出力されます。エラー重大度の指摘だけを修正してから、手順 4 を再実行し、再度検証してください。残りの指摘がすべて警告、または下記のプレースホルダーペアになった時点で、検証を終了してください。read but never assigned は、どのエラーでもカバーされない不備です。プロセスが読み取る値を書き込む箇所がないため、その値を生成するはずの手順が実行されません。MISSING_RESOURCE（警告）と MISSING_BINDING（エラー）は、未解決の1つのノードに関する1つの指摘であり、バインディング側は実際のテナント検索を行います。ノードをデプロイ済みリソースにバインドしてください。ユーザーがプレースホルダー、ドラフト、または境界ハンドオフを求めている場合、あるいは手順 1 で Enabled の候補が見つからなかった場合、識別子を作り出しても MISSING_BINDING は解消できません（ルール 2）。終了コード 1／RetryWillNotFix が想定される結果です。このペアは一度だけ報告し、そのまま続行してください。refresh（手順 6）は未解決のままでも成功します。すべての VARIABLE_DOES_NOT_EXIST 警告を修正してください。これは宣言されていない参照を示しています。開始イベントのスコープにある呼び出し元入力を読み取るノードに対する VARIABLE_NOT_SET 警告は想定内です。references/structural-bpmn.md#validation を参照してください。

   [warning] [(xml)] unknown attribute <type> は、スクリプトタスクのテンプレートにある <uipath:inputSchema type="jsonSchema"> から生じる想定内のノイズです。そのままにしてください。uipath:input、uipath:output、uipath:inputOutput では type が必須です。ここから削除すると、読み込み時に BPMN_PARSE_ERROR ... to be a string で失敗します。ファイルを二分探索したり、ルールを探すために node_modules 内のパッケージバンドルを読んだりしないでください。

   検証は構造上の事前チェックであり、実行時の動作を証明するものではありません。references/cli-conventions.md を参照してください。実行が許可されている場合は、動作が成功したと報告する前に、実行時の変数、要素の実行状況、インシデントを確認してください。

   validate が「unknown command」を報告する場合、または構造ルールを明らかにスキップしている場合は、インストール済みの CLI がそれらのルールに対応する前のバージョンです。更新してください（references/cli-conventions.md を参照）。references/structural-bpmn.md#validation も参照してください。

6. 派生メタデータを更新します。 手順 5 で修正可能なエラーがなくなったら、CLI が管理する4つのパッケージファイルを再生成します。

   uip maestro bpmn refresh <project-path> --output json
   

   0 以外の結果はソースまたは前提条件の失敗として扱います。BPMN または project.uiproj を修正し、手順 4 と 5 を再実行して、再度更新してください。生成された JSON を手作業で修正してはいけません。接続をバインドした後（手順 1）、および パッケージ作成、アップロード、デバッグ、パブリッシュ、デプロイ用の成果物では更新してください。ソースのみの ドラフトでは、手順 3 の開始イベントの編集時だけ更新が必要です。また、トリガー開始の ドラフト（手順 3）では更新をスキップします。全契約（スコープ、冪等性、 バインドルール）については、 references/shared/local-metadata-regeneration-guide.md を参照してください。

操作と診断

作成に加えて、このスキルでは UiPath CLI を通じて Maestro プロジェクトのパッケージ化、配布、実行、診断を行います。

• パッケージ化と操作（プロジェクトのパッケージ化、Studio Web へのアップロード、パブリッシュまたは デプロイ、インスタンスの実行またはデバッグ、ジョブ、インスタンス、インシデント、ライフサイクル操作の管理）：references/operate/CAPABILITY.md を参照してください。
• 診断（インシデント、変数、要素の実行を取得し、失敗した実行を BPMN 要素まで追跡）：references/diagnose/CAPABILITY.md を参照してください。 ランタイムの証拠（インシデント、変数、要素の実行、カーソル、デプロイ済みアセット）は、 uip maestro bpmn ... --output json による読み取りからのみ取得します。1 回の読み取りにつき リテラルコマンドを 1 つだけ実行し、ループは使用しません（同リファレンスのルール 9）。 ローカルの .bpmn ソースと生成されたパッケージファイルは、通常どおりディスクから読み取ります。 その CLI の基盤となるファイルで CLI を代用してはいけません。同リファレンスのルール 3 を参照してください。

クラウド側での変更（アップロード、パブリッシュ、デプロイ、実行、一時停止、再開、キャンセル、 再試行、移行）には、ユーザーの明示的な同意が必要です。また、その前にローカル検証に合格している必要があります。

構造の網羅範囲

このスキルでは、キャンバスがサポートする全範囲の作成方法を説明します。レジストリがテンプレートとして提供するものと、手作業で作成するものは次のとおりです。

構造	ソース
ノードの uipath:* ペイロード（RPA、エージェント、HITL、キュー、ビジネスルール、API ワークフロー、IS コネクター、内部メッセージ、タイマー、スクリプト）	レジストリの xmlTemplate
<uipath:variables> 宣言（それぞれに elementId を含む）	作成（レジストリの不足分）
<bpmn:definitions>／<bpmn:process> の骨組みと名前空間	作成（レジストリの不足分）
シーケンスフロー、conditionExpression、ゲートウェイの default	作成（レジストリの不足分）
ゲートウェイ：排他、並列、包含、イベントベース（複合は保持のみ）	作成（レジストリの不足分）
イベントとイベント定義の対応表：メッセージ、タイマー、エラー、終了（終了イベントのみ）。シグナル／エスカレーション／条件付き／リンク／補償／キャンセル／複数は保持のみ	作成（レジストリの不足分）。ペイロードはキャンバスのシリアライザーに従う
境界イベント：attachedToRef、割り込み／非割り込み（cancelActivity）	作成（レジストリの不足分）
サブプロセス、イベントサブプロセス（triggeredByEvent）、コールアクティビティ	作成（レジストリの不足分）。コールアクティビティのペイロードはレジストリから取得
複数インスタンス／ループの特性	キャンバスの契約に基づいて作成 — レジストリにテンプレートなし（レジストリの不足分）
bpmndi:BPMNDiagram（ノードごとの形状、フローごとのエッジ）	uip maestro bpmn format <file.bpmn> で生成 — レジストリは出力しない（レジストリの不足分）

明示されているレジストリの不足分：レジストリは、構造的 BPMN、シーケンスフローの条件、イベント定義のペイロード、境界イベントの属性、 複数インスタンスのマーカー、ダイアグラムのテンプレートを提供しません。これらは仕様と キャンバスの契約に基づいて references/structural-bpmn.md で作成し、 質問された場合は、不足分としてユーザーに正確に伝えます。

ルール

1. レジストリに登録されたノードのペイロードは、レジストリが管理します。 実行拡張は registry get のテンプレートをもとに作成し、シリアライザーが管理するスキャフォールドメタデータは、構造／キャンバスの契約だけをもとに作成してください。どちらも説明文から作り出してはいけません。
2. 識別子を決して捏造しないでください。 接続 ID、プロセス／キュー／コネクターのキー、アプリ ID、フォルダー ID／パスは、検出結果またはユーザーから取得してください。describe エントリーに Reference が含まれるコネクターフィールドには、ユーザーが記述した名前ではなく、ライブ検索で返された LookupValue を使用してください。references/registry-workflow.mdを参照してください。
3. 構造的な BPMN は作成するものであり、捏造するものではありません。 references/structural-bpmn.md の仕様／キャンバスの契約に従い、レジストリから取得できない情報は正直に明示してください。
4. 確認は1回だけ行い、その後は作成に進んでください。 依頼内容と CLI の証拠から決定できず、誤った回答が取り返しのつかない結果を招くか、識別子の捏造を強いる選択肢に限り、AskUserQuestion で質問してください。作成に着手する前に、そうした質問を1回にまとめて行い、2回目の確認は行わないでください。それ以外はすべて判断して作成し、要約では各前提と、その判断の根拠を明記してください。依頼に承認や確認のために作業を止めないよう記載されている場合は、質問しないでください。入力が画像の場合は、要約ではなく全項目を確認してください。画像からの作成を参照してください。
5. 図は必須です。 インポートは図に基づいて行われます。すべてのノードに BPMNShape、すべてのフローに BPMNEdge が必要であり、ない場合はキャンバスに表示されません。uip maestro bpmn format <file.bpmn> は図全体を生成します。これを .bpmn への最後の書き込みとして実行し、validate または refresh より前に行ってください。これらのコマンドは、図形がないノードがあるとエラーになります。
6. ノードの型は <uipath:type> 子要素として宣言してください。 すべての uipath:activity／uipath:event／uipath:mapping は <bpmn:extensionElements> の内側に配置し、<uipath:type value="<Type>" version="<version>" /> を含める必要があります。ラッパーに type があるテンプレートでは、その属性を削除して子要素を追加し、ラッパー自体の version は残してください。ペイロードに <bpmn:extensionElements> がない場合は追加して、その中にペイロードを配置します。これにより、手順2と3のそのまま貼り付ける指示が上書きされます。<version> はテンプレートの uipath:type から取得し、ない場合は uip maestro bpmn registry get <Type> から取得してください。Orchestrator.StartAgentJob は v2 を使用し、name／folderPath をバインドして、releaseKey／folderId は削除します。イベント拡張型（Intsvc.WaitForEvent、Intsvc.EventTrigger、Maestro.ReceiveMessageEvent、Maestro.SendMessageEvent）は、BPMN のホストが <bpmn:receiveTask> のようなタスク型であっても、必ず <uipath:event> を使用してください。
7. XML コメント内で -- を使わないでください。 XML では --（二重ハイフン）を `` 内に含めることはできません。そのため、CLI コマンドやフラグ（--output、--connection-id、--object-name）をコメントに貼り付けないでください。ファイルを解析できなくなります。コメントは最小限にしてください。
8. 解析する CLI 呼び出しには --output json を使用してください。
9. 常に公開して安全な内容にしてください。 顧客の XML、テナント URL、実際の ID、非公開の名前は含めないでください。references/public-safety.mdを参照してください。例外として、ユーザーのローカルプロジェクト（.bpmn および CLI が生成する bindings_v2.json）では、接続バインディングとそのフォルダーキーに、手順1でバインドした実際の ID を使用してください（プレースホルダーを適用する場合は、手順1の名前を使用）。メモ、およびこのスキルリポジトリに追加する例やフィクスチャは、サニタイズしたままにしてください。
10. クラウドに変更を加える前に、必ず確認してください。 アップロード、公開、デプロイ、実行、一時停止、再開、キャンセル、再試行、移行には、ユーザーの明示的な同意が必要です。まずローカルで検証してください。
11. 再試行はノードの設定であり、キャンバスではありません。 一時的な失敗には、アクティビティの uipath:retry を使用してください。ゲートウェイやタイマーイベントで再試行ループを描いてはいけません。references/structural-bpmn.mdを参照してください。
12. タスク SLA はタスクの設定であり、キャンバスではありません。 承認タイマー、再割り当て、SLA 超過時のエスカレーションは、ユーザータスクに設定します。周囲に境界タイマーを配置して表現してはいけません。
13. エラーイベントサブプロセスは割り込み型であり、終端となります。 エラーイベントサブプロセスが発火すると、通常の経路は停止し、インスタンスは Faulted ではなく Completed として記録されます。そのすべての経路は、明示的に名前を付けた結果で終了する必要があります。そうしないと、処理済みの失敗と成功を区別できません。回復して処理を続行する場合は、代わりにエラー境界イベントを接続してください。
14. 対象システムが異なるだけでは、図形を変える理由にはなりません。 Document Understanding を UiPath エージェントに置き換えたり、Outlook を Gmail に置き換えたりする場合、変更するのはバインディングです。対象システムが異なるというだけでなく、プロセスが実際に異なる場合に図形を変更してください。
15. プロセスを作成するのはあなたですが、その参加者になることはありません。 実行時の推論、分類、抽出を必要とする図形には、それを実行するノード（UiPath エージェント、Document Understanding、ビジネスルールタスク）を配置してバインドしてください。作成時にその処理を行ったり、結果をハードコードしたりしてはいけません。プロセスの説明に単独で「エージェント」と記載されている場合、それは UiPath エージェントを意味し、あなた自身を指すものではありません。
16. 生成されるパッケージファイルは CLI が管理します。 bindings_v2.json、entry-points.json、operate.json、package-descriptor.json を手作業で作成してはいけません。uip maestro bpmn refresh <project-path> を実行して生成してください。非推奨の update-metadata は使用しないでください。ユーザーが依頼した Integration Service のドラフトまたは境界ハンドオフ（手順3）では、これらのファイルは生成しません。CLI が管理する未解決事項を記載した .md メモファイルと .bpmn だけを出力してください。
17. 兄弟スキルに委任したリソース（RPA ワークフロー、API ワークフロー、エージェント、ビジネスルール）を組み込む場合は、次の5段階を順番に実行してください。所有するスキルからリソースを受け取っただけで止めても、作業完了とはなりません。 （ビジネスルールでは手順4を省略します。また、手順3のリリースキーとフォルダーキーは適用されません。ビジネスルールは、registry-workflow.md § ビジネスルールのバインディングに従い、name と folderPath でバインドし、<folderPath>.<name> をキーとして使用します。） (1) まずソリューションを作成または開き（uip solution init。unknown command の場合は旧コマンドの uip solution new）、リソースのプロジェクトはその内部で作成し、.uipx に登録されるようにします。リソースの init と uip maestro bpmn init は、組み立てと同様に、.uipx があるディレクトリから実行してください。ソリューション外で作成したプロジェクトはデプロイできません。

(2) 作成をリソースの担当スキル（例：uipath-api-workflow、uipath-rpa）に委任し、作成されていないひな型ではなく、宣言済みの入力と出力を明記した引数の契約を指定します。(3) リソースを BPMN ノードにバインドする前に、そのリソースをデプロイ（パック、パブリッシュ、solution deploy run）します。リリースキーとフォルダーキーはデプロイ後にのみ存在します。再デプロイするには、uipath-solution のアップグレード手順に従ってください。

(4) ProcessType に基づいてラッパーを選択します。uip or processes list --folder-path <path> --all-fields --output json から読み取ってください（registry-workflow.md）。ローコードエージェントでは Orchestrator.StartAgentJob（タイプ v2、ルール 6）を使用し、ルール 18 ではなく name と folderPath をバインドします。ルール 18 のラッパーでは、同じ応答の Key と FolderKey（デフォルトの一覧と同じパスカルケース）を読み取って、ルール 18 に従ってバインドします。デフォルトの一覧では --all-fields を指定しないと ProcessType が省略されます。架空のキーやプレースホルダーキーは決して使用しないでください。デプロイのたびに両方の値を読み直してください。deploy run は新しいフォルダーを作成するため、以前のデプロイ時の folderKey をそのまま使うと古いフォルダーを参照してしまいます。(5) タスクでライブ実行が禁止されている場合、またはドラフトや引き継ぎが求められている場合を除き、プロセスを実行（uip maestro bpmn debug）して、debug-instance variables-all でノードの出力を確認します。出力で使われたキーに =result.<key> を対応付けます。スカラー値は、スキーマのプロパティ名ではなく、汎用キーの下に現れる場合があります。実行しない場合はスキーマ名を使用し、そのマッピングは未検証として報告してください。ビジネスルールでは、結果全体を =result からの単一の output としてマッピングします。判定や列ごとに個別の出力を設定しないでください。 18. ジョブラッパーのレジストリテンプレート（Orchestrator.StartJob、 ExecuteApiWorkflowAsync、StartAgenticProcess[Async]、 StartCaseMgmtProcess[Async]）は、検証には通るものの実行時に失敗する 未解決の releaseKey を使用します。これは手順 2 と 3 のテンプレートを そのまま貼り付ける指示より優先されます。 これらすべてで、 releaseKey を =bindings.<id> 経由でリソースの Key にバインドします。 ExecuteApiWorkflowAsync の場合に限り、フォルダーの FolderKey を指定した リテラルの folderKey も追加し、folderId、folderPath、name を削除します。 それ以外では、ライブ実行で key:FolderKey のエラーが発生した場合にのみ、 テンプレートの残りのフィールドを維持したまま置き換えます。実行しない場合は、 ノードを未検証として報告してください。詳細： references/registry-workflow.md。

参考資料

トピック	参照先
検出 → テンプレート化 → バインド → 組み立てのループ	references/registry-workflow.md
構造的な BPMN、イベントマトリクス、境界イベント、コンテナー、複数インスタンス、図、検証	references/structural-bpmn.md
繰り返し現れるプロセスの形状の具体的なトポロジーと、形状の組み合わせ方	上記のパターン表 → references/patterns/*-guide.md
ランタイム式、vars.／bindings.／iterator.、=js:（Jint）の構文	references/expression-authoring.md
CLI の規約と副作用の境界	references/cli-conventions.md
コンテンツを公開しても安全な状態に保つ	references/public-safety.md
インスタンスのパッケージ化、アップロード、公開、実行、管理	references/operate/CAPABILITY.md
失敗した実行や正常に動作しない実行の診断	references/diagnose/CAPABILITY.md
プロジェクトの構成と生成されるパッケージファイル	references/shared/project-layout.md