uipath-api-workflow

UiPath API ワークフローアシスタント

UiPath API ワークフローを作成、実行、公開します。UiPath アクティビティ拡張を使用する、CNCF Serverless Workflow DSL 1.0.0 に準拠した JSON です。ワークフローは @uipath/api-workflow-executor と uip api-workflow run を通じて実行され、uip solution pack によって Type: "Api" プロジェクトとしてパッケージ化されます。

TDD ゲート — 最初にお読みください（ルール 22）。 作成／編集の依頼では、ワークスペースやソリューションのルートではなく、Workflow.json と同じ階層にある <project>/evals/ を確認します。存在しない場合、Evaluations はオフです。テストやループモードについて質問せず、通常どおり作成してください。存在する場合は、作成に着手する前に停止し、既存の行を維持／変更するか、テストを空の状態で追加するか、また、すべて合格するまで実行／再試行するか、一度だけ作成するかを確認してください。両方の回答を得たら、スキーマを宣言し、最初に evals を作成／更新してから、ワークフローを作成します。質問しないよう依頼された場合は、これらの質問を省略しますが、実行への同意を得たことにはなりません。実行を求められた場合に限り、行を実行してください。その後の動作変更では、影響を受ける期待値を変更するかどうかを確認する必要があります。

このスキルを使用する場合

API ワークフローの JSON の作成／編集や、Sequence、Assign、JavaScript、Log Message、If、ForEach、DoWhile、Break、TryCatch、Wait、Response、HTTP Request、コネクタアクティビティを使用する場合に使います。Studio Web のコネクタワークフローやプロジェクトの evals/ レイアウトについては、コネクタおよびテストのリファレンスを使用してください。

• ローカルでの実行、検証、ビルド／パッケージ化、公開

• API ワークフローでファイルを扱うことを希望する場合 — ファイル入力を受け取る、ファイルを base64 として API に送信する、base64 ペイロードをファイルに戻す、または JobAttachment、$helpers.file、serializeData()、--input-file／--output-dir について質問する場合。references/files-and-base64.md を参照してください。

• コネクタイベント（Slack ボタンのクリック、新しい Outlook カレンダーエントリなど）を起点にワークフローを開始する場合や、既存のトリガー（call: "UiPath.IntSvcEvent"）を調査／変更する場合。references/trigger-authoring-guide.md を参照してください。

• 公開済みワークフローの操作

.flow Maestro フロー（uipath-maestro-flow）、.xaml またはコード化された RPA（uipath-rpa）、コード化されたエージェント（uipath-agents）、Coded Web Apps（uipath-coded-apps）には使用しないでください。API ワークフローの evals は、Workflow.json と同じ階層にある evals/ と、evals/<scope>/eval-sets/ のみが対象です。evals/eval-sets/ はローコードエージェント用であり、Flow の evals は uipath-maestro-flow 用です。

基本原則

0. 判断を伴う分岐は、構築前にエスカレーションします。 接続を利用できない場合、厳選されたアクティビティが存在しない場合、ドキュメント化されていない HTTP フォールバックが必要な場合、想定される入力が欠落している場合、または構造の異なる複数のワークフローが考えられる場合は、共通する調査のみを行い、トレードオフと推奨案を提示して停止してください。すべての分岐を構築しないでください。機械的に決められる選択については、エスカレーションは不要です。

1. 書き始める前に把握します。 編集する場合は既存のワークフローを読み、作成する場合は関連するテンプレートを読んでください。

2. 最小限から始め、正しくなるまで反復します。 アクティビティを一度に 1 つ追加します。追加するたびに --no-auth --output json を指定して実行します。問題が発生したら修正し、繰り返してください。

3. 実行前に検証します。 uip api-workflow validate は自律的にオフラインで実行されます。run はランタイム検証であり、HTTP や接続にアクセスする可能性があるため、同意が必要です。

4. カテゴリ別に修正します： 構造 > 式 > アクティビティ設定 > ロジック。

重要なルール

1. ワークフロー JSON。 トップレベルには、dsl: "1.0.0" を持つ document、language: "javascript" と mode: "strict" を持つ evaluate、およびルートシーケンスを 1 つ含む do が必要です。ルートシーケンスの名前は異なる場合があるため、ファイルを読んで確認してください。references/workflow-file-format.md を参照してください。

2. WorkflowStart。 ルートシーケンスの最初に置き、変数のデフォルト値を $context.variables に読み込み、入力を $input に渡します。削除、名前変更、変更をしてはいけません。isTransparent: true を使うのはこれだけです。

3. アクティビティオブジェクトとキー。 各アクティビティは、do 配列内の単一キーオブジェクトです。#Wrapper、#Then、#Else、#Body などのラッパー接尾辞を含め、キーはすべて一意である必要があります。

4. エクスポート。 Log Message 以外のすべてのアクティビティでは、出力をエクスポートする必要があります。Assign では { ...$context, variables: { ...$context.variables, ...$output } } を使用し、それ以外では { ...$context, outputs: { ...$context?.outputs, "<ActivityKey>": $output } } を使用します。references/expressions-and-context.md を参照してください。

5. リテラル式。 Assign の set、Response、If の when、および変数コンテキストでは、文字列リテラルを "${'literal'}" のような式にする必要があります。Studio Web は保存時に裸の "literal" を "${literal}" に書き換え、実行時にエラーになるためです。数値、ブール値、参照はラップする必要はありません。一方、コネクターの bodyParameters、queryParameters、pathParameters では裸のリテラルを使用し、参照は引き続き式として記述します。references/connector-activity-discovery.md および references/troubleshooting.md を参照してください。

6. Assign。 各 Assign で設定する変数は1つだけにしてください。Studio Web は複数キーの set を折りたたむため、Assign アクティビティを順番に配置し、変数のエクスポートを通じて各キーを1つずつマージします。

7. If。 If_N#Wrapper の中に If_N、If_N#Then、If_N#Else を配置します。両方の分岐の末尾は then: "exit" とし、when は ${...} でラップします。references/control-flow-patterns.md を参照してください。

8. ループ。 ForEach と DoWhile には #Body が必要です。ForEach ではインデックスを考慮した累積を使用し、反復0でリセットします。DoWhile では単純な累積を使用します。each と at は式ではなく、通常の名前です。

9. DoWhile。 for.in は常に "${ [1] }" とし、反復は doWhile で制御します。ループ本体で条件変数を更新しないと、ループが無限に続く可能性があります。

10. ネストされたループ。 各ループで異なるイテレーター名とインデックス名を使用します。

11. ループ／catch のバインド。 for.each、for.at、catch.as は $ を付けずに宣言しますが、式やスクリプト内では $ を付けて参照します。"row" は $row を、"idx" は $idx を、"err" は $err をバインドします。$ を省略すると、未定義名エラーが発生します。

12. Break。 Break が抜けるのは最も内側のループだけであり、#Body 内でのみ有効です。If の中に配置し、break は文字列 "true"、then: "exit"、set: "${$input}" にする必要があります。ネストされたループから抜けるには、フラグを設定して外側のループで確認します。references/control-flow-patterns.md を参照してください。

13. ワークフローの入力。 先頭以外のアクティビティでは、$input.<name> ではなく $workflow.input.<name> を使用します。$input は現在のタスクへの入力であり、前のアクティビティの出力である場合があります。

14. JavaScript。 スクリプトでは $context、$workflow、$input をグローバルとして読み取り、値を返す必要があります。標準の Studio Web run.script.arguments の枠組みはそのまま使用してください："${{ \"$context\": $context, \"$workflow\": $workflow, \"$input\": $input }}"。実行時には無視されます。ログ出力には Log Message を使用し、スクリプト内で console.* を使用しないでください。そのコードは console.log|warn|error(<message>) のみとし、return、export、末尾の ; は付けません。references/task-types.md を参照してください。

15. Response。 markJobAsFailed は response と同じ階層に置きます。常に then: "end" を使用し、then: "exit" は分岐／ループ用です。オブジェクトのレスポンスには、個々のフィールドを別々に埋め込むのではなく、"${{ key: $context.variables.value }}" のような式を1つ使用します。単一の値には "${$context.outputs.Activity}" または "${'done'}" を使用できます。${ { ... } } と ${{ ... }} はどちらも有効です。一貫して使用してください。両者を組み合わせてはいけません。${{ { ... } }} は validate を通過しますが、実行時に Unexpected token '{' で失敗します。

    • ディスク上のファイルを正とします。 Studio Web で保存した後は、ディスク上のファイルを正として扱い、必要な回避策を再適用したうえで uip api-workflow run --no-auth を再実行してください。

16. コネクターと HTTP はレジストリー生成のみを使用します。 uip api-workflow registry resolve を実行してから stub を実行してください。uiPathActivityTypeId、metadata.configuration、アクティビティの種類、エンドポイント、SlotKey、ExportBucketKey を推測してはいけません。stub の出力をそのまま使用してください。

• キーワードによる resolve が見つからなくても、キュレーション済みのアクティビティがないとは限りません。トークンを AND 条件で照合するためです。uip is connectors list --filter で製品／ベンダーを特定し、フォールバックする前に uip is activities list <connector-key> で一覧表示してください。

• IntSvc／ベンダーのアクティビティには、uip is connections ping <uuid> の成功が必要です。一覧表示の結果が空、または失敗した場合は、フィルターなしでの一覧表示を試し、次に --all-folders を指定して、条件に一致する別の接続を ping してください。

• ping に成功する接続がない場合は、処理を停止し、明示的なプレースホルダー使用の同意を得て続行するか、接続が修正されるまで待つかを確認してください。黙って選択してはいけません。

• 置換用のセンチネルを with.connectionId、connectionResourceId、HTTP URL に入れてはいけません。書き込む前に、実際の値を使用して再度 stub を実行してください。

• stub を実行するたびに、リソースの説明または stub の入力を使って必須フィールドを確認し、必要に応じて --inputs を指定して再度 stub を実行してください。

• コネクターのパラメーターには、フラットなドット区切りのキーと値をそのまま使用してください。${'literal'} は使用しないでください。

• ベンダーの接続 UUID を使って UiPath.Http を使用してはいけません。IntSvc の結果はラップされています。$context.outputs.<ExportBucketKey>.content.<field> を読み取ってください。

• nextPage パラメーターを受け取る IntSvc のリストおよび検索アクティビティは、呼び出しごとに 1 ページを返します。stub の with.method が GET で、.content が配列の場合は、stub の with に "maximumRecordsReturned": -1（または正の上限値）を追加し、ループは記述しないでください。ランタイムが上限まで各ページを取得し、1 つの .content リストにまとめます。手作業でリテラルの数値として追加してください。stub はこの値を省略し、--inputs はこの値を削除し、式を指定しても評価されません。別のメソッドを使う場合、または各ページを個別に処理する必要がある場合は、アクティビティの .page 出力を使ってループし、.page がない場合、または .page.hasMorePages が false の場合に停止してください。生の elements-next-page-token ヘッダーを基準に判定してはいけません。このヘッダーは最後のページを含むすべてのページに存在します。詳しくはreferences/connector-activity-discovery.mdを参照してください。

• Solutions モードでは、uip api-workflow bindings sync --workflow <Workflow.json> を実行して IntSvc のバインディングを同期し、uip solution resources refresh --solution-folder <path> を実行して更新してください。HTTP、コネクター以外、スタンドアロンプロジェクトの場合は不要です。

• 検出フロー、フィールド形式のルール、ページネーション、マルチパートについては、references/connector-activity-discovery.mdを参照してください。

16a. コネクターイベントトリガーは、独立したカタログ、独立したアクティビティ形式、2 つ目の成果物です。 ワークフローをイベント（Slack ボタンのクリック、新しい Outlook カレンダーエントリなど）から開始する必要がある場合は、uip api-workflow registry resolve "<keyword>" --kind trigger を実行してから registry stub を実行してください。手作業で作成してはいけません。stub はルート Sequence の do 配列内の 1 か所だけ、WorkflowStart の直後（do[0].Sequence_1.do[1]）に配置してください。If／ForEach／TryCatch の内部、別のアクティビティの後、2 つ目のトリガーとして配置してはいけません。validate は、配置の誤りや 2 つ目のトリガーを拒否します。GenericTrigger には --object-name が必要です。フロー全体、フィルター構文、アンチパターンについては、references/trigger-authoring-guide.mdを参照してください。

- **トリガーを追加または編集するたびに、`uip api-workflow bindings sync` を実行してください。** これにより、デプロイ時に Orchestrator イベントトリガーを登録する `bindings_v2.json` の `EventTrigger` エントリが書き込まれます。**これを実行しない場合、ワークフローは検証、パック、公開、デプロイのすべてに問題なく通りますが、一度も起動しません。** これを検出するゲートはありません。Solutions モードでは、その後に `uip solution resources refresh` を実行してください（ルール 16）。
- **`webhooks` トリガーは、入力なしではローカルで実行できません。** `uip api-workflow run` は `polling` の場合にのみライブイベントを再生します（ルール 21 に基づく副作用があります）。どちらのモードでも、イベントペイロードと同じ形式の `--input-arguments` を指定すると、ワークフローの残りの部分をオフラインで実行できます。

17. CLI 入力。 JSON を文字列として渡します：--input-arguments '{"key":"value"}'。無効な JSON の場合は終了コード 1 で終了します。

18. CLI 出力。 --output json で解析します。成功時：{ "Result": "Success", "Code": "WorkflowRun", "Data": {...} }、失敗時：{ "Result": "Failure", "Message": "...", "Instructions": "..." }。失敗時の終了コードは 1 です。

19. プロジェクトの作成と公開。 uip api-workflow init <name> でひな形を作成します。プロジェクトファイルを手作業で組み立てないでください。プロジェクトコマンドには build <projectDir> と pack <projectDir> <outputDir> があります。uip solution pack と uip solution publish を使用してください。uip api-workflow publish はありません。ソリューションの種類は "Api" です。

19a. Init の構成と登録。 ソリューションディレクトリ内で uip api-workflow init <name> --output json を実行します。これにより、project.uiproj、Workflow.json、entry-points.json、bindings_v2.json が作成され、最も近い .uipx にプロジェクトが登録されます。--skip-solution-registration は、スタンドアロンの CLI／ローカルプロジェクトとして明示的に要求された場合にのみ使用してください。必ず完全なプロジェクトを作成し、ワークフローファイルだけを作成しないでください。コネクタデータを確認するだけのものなど、一時的な検証用ワークフローはプロジェクトやソリューションのフォルダーの外（例：/tmp）に作成し、完了前に削除してください。ソリューション内に余分なプロジェクトを残さないでください。ソリューションのプロジェクトを追加／削除したり、既存のプロジェクト ID を変更したりしないでください。レガシーな project.json については、新しい兄弟プロジェクトを初期化して内容をその Workflow.json に移すか、その場で変換してください。references/troubleshooting.md を参照してください。実行時に成功しても、Studio Web との互換性が証明されるわけではありません。互換性を保証するのは init で生成された構成です。

20. 静的検証。 オーサリング／編集サイクルごとに、自律的に実行する最後のコマンドとして uip api-workflow validate <Workflow.json> --output json を実行します。Result: "Failure" の場合は Instructions を読み、JSON パスで示されたアクティビティを修正し、Data.Status: "Valid" になるまで繰り返します。重複した oneOf によるノイズより、セマンティックテールのエラーを優先して対処してください。

    検証で検出できるのは、不正な JSON、未知の型、必須フィールドのエラー、不適切な evaluate 設定、重複または空の変数、空のタスクリストです。接続の不備、誤ったリソース ID、実行時の式エラー、ラップされていないリテラル、複数キーの Assign セットは検出できません。これらの確認には、ユーザーの同意を得てから uip api-workflow run を実行する必要があります。

21. 実行時の同意。 明示的な同意なしに uip api-workflow run を実行しないでください。検証後、実行を省略するか、--no-auth で実行するか、認証付きで実行するかを尋ねてください。制御フローのみのワークフロー、および ImplicitConnection を使用する HTTP には --no-auth を推奨してください。認証付き実行は、実際の副作用を確認した後の IntSvc に限って推奨してください。認証付きの呼び出しでは、メールの送信、チケットの作成、ファイルのアップロードが行われる場合があります。ループモードの同意は --no-auth による eval 行の実行を許可しますが、認証付きのコネクタ実行には引き続き明示的な同意が必要です。この制限の対象は uip api-workflow run のみであり、uip solution pack／publish には適用されません。ビルド、パッケージ、公開の依頼には実行についての確認を挟まずに対応してください。ローカル実行は別の依頼として扱い、求められた場合にのみ実行します。

22. TDD ゲート。 作成／編集のたびに <project>/evals/ を確認します。存在しない場合、テストを提案したり、フォルダーを作成したり、ループモードに言及したりしないでください。存在する場合、Workflow.json または evals を変更する前に作業を止め、既存のケースを変更するのか、新しいケースを追加するのか、また、すべて合格するまで実行／再試行するのか、一度だけ作成するのかを確認します。行が存在する場合は、その件数を報告し、それぞれの概要を説明します。空の場合は、2～3件のケースを提案します。回答を得た後、input.schema と output.schema を宣言し、evals を更新して作成します。その後、ループモードの場合に限り行を実行し、一度だけ作成するモードでは引き継ぎます。動作を変更する場合は、影響を受ける行を特定し、期待値を変更するか確認します。質問しないよう求められた場合、既存のテストは維持しますが、ランタイムの実行許可とはみなしません。references/testing-and-evals.md §3 を参照してください。

23. ファイルはバイト列ではなく参照です。base64 もファイルです。 ファイルの入力と出力は、Orchestrator の blob を参照する JobAttachment（{ ID, FullName, MimeType, Metadata? }）です。$workflow.input.<file> がバイト列になることはありません。

    • 2 つのアクティビティ。 どちらも $helpers.file.* の呼び出しで識別される run.script タスクです（validate が確認する内容です）。File to Base64 は base64 テキストを含む新しい参照を返し、Base64 to File はバイナリ参照を返します。スクリプトは return 式を 1 つだけ含み、それ以外は記述できません。Studio Web は前後の文、2 つ目の引数、または余分なオプションキーを警告なしで削除します。validate が検出するのは余分な文のみのため、余分な引数やキーがあるとアクティビティが引き続き壊れることがあります。前処理は別の JavaScript アクティビティに記述してください。正確な形式と例については、references/files-and-base64.md を参照してください。
    • 結果の読み取り。 $context.outputs.<Key>.output を使用します。
    • コンテンツのインライン化。 <ref>.serializeData() を HTTP 本文または Response フィールドに直接使用します。これは読み取りを遅延させるマーカーなので、保存したり、スクリプトロジックで使用したりしないでください。JSON 本文内にネストする場合に機能するのは、base64 参照（File to Base64 の出力）のみです。バイナリファイルのマーカーや参照だけをネストすると、送信時にエラーになります。バイナリファイルは本文全体として送信するか、事前に変換してください。
    • 名前付け。 fileName と mimeType は、未加工の base64 文字列にのみ適用されます。参照には名前が保持され、エンジンはバイト列から種類を判別します。そのため、.txt を往復させると拡張子がなくなることがあります。
    • 実行。 どちらのヘルパーにも Orchestrator の blob ストレージが必要です。

    uip api-workflow run --no-auth は、そのようなワークフローの実行を事前に拒否します。サインインした状態で実行してください（uip login を使用し、--no-auth は指定しません）。ただし、ルール 21 の「yes」は引き続き必要です。--input-file <name>=<path> でローカルファイルを渡すと、アップロードされ、$workflow.input.<name> として届きます。返されたファイルを収集するには --output-dir <dir> を指定します（出力内の各参照に LocalPath が追加されます）。テナントの Attachments API がフォルダーを必要とする場合は、--folder-key <guid> を指定してください。出力表示では、CLI がキーを PascalCase に変換します（ID → Id）。

    形式、具体的な例、注意点については、references/files-and-base64.md を参照してください。

ワークフローの各フェーズ

フェーズ 0：調査

プロジェクトディレクトリで evals/ を確認し、存在する場合は evals/<scope>/eval-sets/*.json と評価器を読み込みます。編集の場合は、Workflow.json、キー、変数、スキーマ、エクスポートパターンを読み込みます。作成の場合は、assets/templates/api-workflow-template.json、最も近い条件分岐／ループ／ネストした制御フローテンプレート、必要に応じて references/control-flow-patterns.md を読み込みます。作成を始める前にルール 22 を適用してください。

フェーズ 1：計画

アクティビティ、一意のキー、変数、入力、出力、ネストを選択します。変数には Assign、カスタムロジックには JavaScript/JsInvoke、ログ記録には Log Message、分岐には If、コレクションには ForEach、反復には DoWhile、エラーには TryCatch、一時停止には Wait、終了には Response を使用します。If の中では Break を使用し、HTTP／コネクタにはレジストリから生成された UiPath.Http または UiPath.IntSvc を使用します。ファイル／base64 の場合、File to Base64 はファイル（入力またはダウンロードしたもの）をインライン API 本文用の base64 にエンコードし、Base64 to File は base64 ペイロードをファイルに戻します（ルール 23）。レジストリの検索で厳選されたオペレーションが見つからない場合に限り、汎用コネクタアクティビティを使用します。references/task-types.md をお読みください。

フェーズ 2：生成または編集

リファレンスから最小限の形をコピーします。テンプレートから作成し、ルートシーケンスの WorkflowStart の後にアクティビティを配置します。編集する場合は、規則を維持し、十分に一意なコンテキストを使用します。ルール 22 が適用される場合は、eval 行の前にスキーマを宣言します。スケルトン：

{
  "document": { "dsl": "1.0.0", "name": "...", "version": "0.0.1", "namespace": "default", "metadata": { "variables": { "schema": { "format": "json", "document": { "type": "object", "properties": {}, "title": "Variables" } } } } },
  "input": { "schema": { "format": "json", "document": { "type": "object", "properties": {}, "title": "Inputs" } } },
  "output": { "schema": { "format": "json", "document": { "type": "object", "properties": {}, "title": "Outputs" } } },
  "do": [{ "Sequence_1": { "do": [{ "WorkflowStart": {} }] } }],
  "evaluate": { "mode": "strict", "language": "javascript" }
}

フェーズ 3：検証してから、同意を得て実行

uip api-workflow validate ./<project>/Workflow.json --output json
uip api-workflow run ./<project>/Workflow.json [--no-auth] --output json

自律的に検証し、有効になるまで修正してから、実行前に確認を求めます。質問では具体的な副作用（メールの送信、チケットの作成など）を明示し、その後は返答を待ちます。実行がスキップされた場合は、正確なコマンドを提示します。

失敗は「構造 > 式 > アクティビティ設定 > ロジック」の順に切り分けます。references/troubleshooting.md を参照してください。

フェーズ 4：パッケージ化、公開、運用

パッケージ化に必要なのは validate の成功（ルール 20）であり、ローカル実行ではありません。ビルド／パッケージ化／公開のリクエストでは、すぐにパックします（ルール 21 は run を制限しますが、pack は制限しません）。init で生成された形を確認してから、次を実行します。

uip solution pack <solutionDir> <outputDir> --name <PACKAGE_NAME> --version 1.0.0 --output json
uip solution publish <outputDir>/<package>.zip --tenant <TENANT_NAME> --output json

公開には uip login が必要です。パッケージャーは Type: "Api" を検出し、ワークフローを検証してコピーし、デプロイメタデータを生成して、.zip 内に .nupkg を作成します。デプロイ後は、Orchestrator／API トリガー、ジョブ、接続、ログ、トレースを通じて運用します。ローカルの uip api-workflow 動詞では、公開済みワークフローを操作できなくなります。references/operating-published-workflows.md を参照し、必要に応じて詳細な作業を uipath-platform または uipath-troubleshoot に委任してください。

クイックスタート（ゼロから作成）

uip solution init <SolutionName> --output json
cd <SolutionName>
uip api-workflow init <ProjectName> --output json
# If <ProjectName>/evals/ exists, stop and apply rule 22; otherwise edit after WorkflowStart.
uip api-workflow validate ./<ProjectName>/Workflow.json --output json
# Ask for consent, then run if approved:
uip api-workflow run ./<ProjectName>/Workflow.json --no-auth --output json
uip solution pack . ./build --name <PackageName> --version 1.0.0 --output json
uip login
uip solution publish ./build/<package>.zip --tenant <TenantName> --output json

リファレンスナビゲーション

ファイル	用途
references/workflow-file-format.md	JSON スケルトン、スキーマ、変数、WorkflowStart、Studio Web の構造
references/http-retry-config.md	ワークフローレベルの HTTP リトライ／バックオフ
references/task-types.md	アクティビティの形状、必須フィールド、エクスポート、よくある間違い
references/control-flow-patterns.md	ネストされた If、ループ、TryCatch、Break、分岐、一意性を保つキー
references/connector-activity-discovery.md	uip api-workflow registry resolve + stub を使った HTTP Request／Gmail／Outlook／GitHub／Slack などのアクティビティの作成 — 検出フロー、接続の検証、フィールド形状のルール、ページング、マルチパート
references/trigger-authoring-guide.md	コネクタイベントトリガー：registry resolve --kind trigger + stub、UiPath.IntSvcEvent の形状、必須の EventTrigger バインディング、JMESPath フィルター、ポーリングと Webhook
references/expressions-and-context.md	式、コンテキスト、入力、スクリプト、エクスポート、厳密モード
references/files-and-base64.md	ファイルと Base64 — JobAttachment の参照、File to Base64／Base64 to File アクティビティ（正確な JSON、$helpers.file.*）、インラインボディ／レスポンス用の serializeData()、ローカルファイルを渡して実行結果からファイルを取得する方法、注意点

| references/cli-reference.md | API ワークフロー、ソリューション、ログイン、ビルド、パック、検証、公開 |

| references/operating-published-workflows.md | 公開済みトリガー、接続、ジョブ、ログ、トレース |

| references/troubleshooting.md | ランタイム、構造、式、コネクター、レスポンス、パッケージ化、公開に関する失敗 | | references/testing-and-evals.md | 評価の仕様、スコアリング、生出力、テストを成功するまで繰り返すプロトコル |

テンプレート

• assets/templates/api-workflow-template.json — 有効な空のスケルトン。

• assets/templates/conditional-workflow-example.json — 条件分岐／エラー処理。

• assets/templates/loop-aggregation-example.json — ループ集約。

• assets/templates/nested-control-flow-example.json — 深くネストされた制御フロー。

• assets/templates/file-base64-roundtrip-example.json — ファイル — document ファイル入力 → File to Base64 → Base64 to File → 両方の参照を返す Response。Studio Web が 2 つのアクティビティに対して出力する正確な run.script の形状（ルール 23）。サインイン済みの実行でエンドツーエンドの動作を検証済み：ローカルファイルを入力 → .base64 参照 → デコードしたファイルを出力し、バイト列が一致します。

• assets/templates/trigger-workflow-template.json — イベント駆動型スケルトン：WorkflowStart → UiPath.IntSvcEvent トリガー → ペイロードを読み取る Response。<REPLACE_WITH_*> の接続 UUID とトリガータイプ ID は仮の値です。実際の値を得るには再度 stub を生成してください（ルール 16、16a）。

• assets/templates/connector-call-example.json — ImplicitConnection を含む、レジストリで生成された HTTP。

• assets/templates/vendor-curated-call-example.json — IntSvc アクティビティ。書き込む前に接続の仮の値を置き換えてください。

• assets/templates/solution-connection-resource-template.json — Solutions モードの IntSvc 接続リソース。

アンチパターン

• call: "http" は使用せず、レジストリで生成された UiPath.Http を使用してください。

• コネクターのパラメーターリテラルを ${'literal'} でラップしないでください。

• 接続や URL の置換用センチネルを含めないでください。

• 後続のワークフロー入力を $input.<name> から読み取らないでください。

• 絶対にファイル入力や File to Base64 の結果を文字列として扱わないでください。どちらも JobAttachment 参照です。ファイルの内容をインライン化するのは、HTTP ボディ／Response 内で <ref>.serializeData() を使う場合のみとし、Assign やスクリプトでは使用しないでください。また、JSON ボディのフィールド内で使用できるのは File to Base64 の出力に限ります（ボディ内にネストした $workflow.input.document.serializeData() は「Raw bytes cannot be embedded in JSON」というエラーになります）。ルール 23 を参照してください。

• 絶対に$helpers.fileToBase64(...)／$helpers.base64ToFile(...) と記述しないでください。ヘルパーは $helpers.file. の下にあります。validate はタスクを拒否し、ランタイムは is not a function と表示します。ルール 23 を参照してください。

• 同意なしに自律的に実行したり、認証が必要なベンダーへの呼び出しを実行したりしないでください。

• 旧式のプロジェクトを手作業で組み立てたり、単独の Workflow.json を出力したり、solution projects の追加／削除を使用したりしないでください。

• ランタイム、パック、公開の成功を Studio Web との互換性の証明として扱わないでください。

• PascalCase の CLI 表示データから期待される eval 出力をコピーしないでください。キーは output.schema と Response から導き、期待値には生の出力を使用してください。

• evals/ が存在する場合、先に作成しないでください。ルール 22 を適用してください。存在しない場合は、evals を作成したり提案したりしないでください。古くなった期待値を満たすためにロジックを変更しないでください。

無限ループの防止

コマンドが同じエラーで 2 回失敗した場合は、再試行せずに調査してください。操作ごとに最大 3 回まで試行し、その後は停止して、試した内容を報告してください。

• 認証／組織のエラー：ユーザーに uip login の実行を依頼してください。

• ファイルが見つからないエラー：ls でパスを確認してください。

• 構造に関するエラーが繰り返し発生する場合：ワークフローと関連するリファレンスを読み直してください。