field-service-data-capture-form-editor-configure

データ入力フォームを編集する（組織内）

このスキルは、接続済みの組織にすでに存在するフローにパッチを適用します。信頼できる情報源は、Tooling Flow sObject からリアルタイムで取得する、デプロイ済みフローの Metadata JSON です。仕様ファイルも、.flow-meta.xml も、zip も、SFDX プロジェクトもありません。このスキルは JSON を取得し、メモリ上で編集してから、PATCH で書き戻します。

ランタイムの仕様： このスキルでの組織とのやり取りはすべて、Codey ランタイムを通じてディスパッチされる REST 呼び出しです（ローカルでは dispatch、共有サーフェスではホスト型の Headless 360 MCP を使用します）。このスキルは実行環境に依存しません。sf CLI も、ローカルの Python も、一時ファイルも、スクラッチ SFDX プロジェクトも不要です。認証プローブ、フローの取得、再デプロイはそれぞれ単一の REST 呼び出しで行います。JSON パッチはエージェントがインラインで作成します。シェルコマンドを実行しないでください。

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

• ユーザーが既存のフロー（Inventory_Transfer、Asset_Inspection など）を指定し、変更を依頼した場合。
• ユーザーが Flow Builder の URL を貼り付け、変更を依頼した場合。
• ユーザーがデプロイ済みフローのデプロイエラーや実行時のバグについて説明した場合。

ユーザーがゼロから作成する場合（文章、PDF、画像）は、代わりに design-* スキルに振り分けてください。

ワークフロー

1. 組織の認証を確認する

簡単な認証プローブ（SELECT Id FROM Organization LIMIT 1 をディスパッチする GET /services/data/vXX.0/query）で、接続済みの組織に到達できることを確認します。

• 2xx で totalSize=1 → セッショントークンは有効です。続行してください。
• 401/403 → 組織の再認証が必要です。ユーザーにその旨を伝え、停止してください。（Codey ランタイムが接続済み組織の解決と更新を行います。このスキルは組織のエイリアスを管理しません。）

2. ライブフローの Metadata JSON を取得する

Tooling Flow sObject では、フロー定義を JSON の Metadata フィールドとして公開しています。デプロイツールが組み立てて POST するものと同じ形式です。取得は CLI もファイルも使わず、2 回の呼び出しで完了します。

1. API 名から最新バージョン ID を特定します。 次の内容で GET /services/data/vXX.0/tooling/query をディスパッチします。

   SELECT Id, ActiveVersionId, LatestVersionId FROM FlowDefinition WHERE DeveloperName = '<FlowApiName>'
   

   最新バージョン（LatestVersionId）を編集し、古いアクティブバージョンではなく、最新のドラフトを基にパッチを作成します。LatestVersionId が null の場合は、ActiveVersionId を使用します。

2. Metadata のデータを読み取ります。 GET /services/data/vXX.0/tooling/sobjects/Flow/<versionId> をディスパッチし、レスポンスから Metadata オブジェクトを取得します。この JSON がフロー本体です。画面、選択肢、判断、変数、画面以降の処理チェーンが含まれます。形式については、../fs-data-capture-form-deployer/reference/flow-metadata-json.md を参照してください。

FlowDefinition クエリの結果が 0 行の場合、API 名が間違っているか、ユーザーが別の組織を参照しています。再試行する前にユーザーに確認してください。必要であれば、SELECT DeveloperName FROM FlowDefinition ORDER BY DeveloperName を指定した GET /services/data/vXX.0/tooling/query をディスパッチして、組織内の候補フローを一覧表示します。

3. 取得した Metadata JSON とルールシートを読む

パッチを適用する前に、取得した Metadata JSON を読み、現在の構造を把握してから、fs-data-capture-reference/SKILL.md を読んで、プラットフォームの厳格な制約を確認してください。フローが XML と JSON のどちらで表現されていても、制約は同じです。繰り返される XML 要素は JSON 配列になるため、「グループ化」は「配列」になります（../fs-data-capture-form-deployer/reference/flow-metadata-json.md の JSON↔XML マッピングルールを参照）。

特に次の点に注意してください。

• 要素配列：screens、choices、decisions、recordLookups、recordCreates、recordUpdates、loops、assignments、variables は、それぞれ単一の JSON 配列です。新しい要素は該当する配列に追加してください。トップレベルキーを重複して追加してはいけません。
• CUD の順序：コネクターチェーン内では、CUD（recordCreate／recordUpdate／recordDelete）の後にレコード検索や画面を置くことはできません。連続する CUD の間に判定を置くこともできません。
• .AllItems と .AddedItems の Repeater アクセサー：デプロイ済みのフローで使われているものを使用し、変更しないでください。
• 表示ルール：visibilityRule.conditions のエントリーでは、leftValueReference は親フィールド名ではなく、選択肢の API 名です。
• 表示ルールの背後に必須フィールドを置くアンチパターン（fs-data-capture-reference の SKILL.md を参照）。
• isLlmTargetable：生の JSON ブール値ではなく、{ "stringValue": "true" } 形式のラッパーとして格納されます。取得したフローで使われている形式に合わせてください。

fs-data-capture-reference/SKILL.md の末尾にある禁止パターンの表は、「このパッチを壊す原因となるもの」を確認する最も手早い参照先です。

4. パッチを計画し、ユーザーに確認する

編集する前に、次の内容をユーザーに伝えてください。

1. 変更内容 — 対象となる具体的な要素、行（path:line 形式で示す）、および変更後の状態。
2. 変更にスキーマの並べ替えが必要かどうか — たとえば、<recordLookups> が存在しない状態で新たに追加する場合は、適切なグループに配置する必要があります。その点を明示してください。
3. 有効化ステータスに関するリスク — パッチはフローの新しいドラフトバージョンとしてデプロイされます。ユーザーが Flow Builder で新しいドラフトを有効化するまで、（存在する場合）有効なバージョンは引き続き実行されます。この点を伝えてください。
4. 指摘すべき事項 — 既存の問題、非推奨のパターン、正しく機能していないように見える検証ルールなど、気づいた点があれば伝えてください。無関係な問題は自動修正せず、ユーザーに知らせてください。

編集を開始する前に、AskUserQuestion を使って承認を得てください。選択肢：

• 適用してデプロイ — 続行します。
• 変更内容を先に見せて — チャット内に、編集対象の JSON サブツリー（変更する特定のフィールド、画面、またはルール）の変更前と変更後を表示してから、再度確認します。ファイルは書き込まず、ユーザーが PATCH を承認するまでパッチはメモリ内に保持されます。
• キャンセル — デプロイせずに中止します。

明示的な承認を得るまでは、ステップ 5 に進まないでください。

5. パッチを適用する

ステップ 2 で取得したメモリ内の Metadata JSON オブジェクトを編集します。次のガイドラインに従ってください。

• 適切な配列に追加します。 画面を追加する場合は screens 配列に、選択肢を追加する場合は choices に、変数を追加する場合は variables に追加します。同じ名前のトップレベルキーを2つ作成しないでください。
• ブール値と数値は JSON スカラーのままにします。 "isRequired": true、"locationX": 0 のようにし、文字列にしないでください。型付きの値ラッパーではキーを維持します（{ "stringValue": "X" }、{ "booleanValue": true }、{ "elementReference": "Foo" }）。
• 既存の要素では locationX / locationY を維持します。 新しい要素では両方を 0 に設定します。Flow Builder を開くと再レイアウトされます。
• 変更が Repeater に関係する場合は、ループ内の既存の .AllItems / .AddedItems アクセサーを維持します。 アクセサーを切り替えると、実行時の動作が壊れます。
• 新しいフィールドを追加する場合は、同じフロー内の兄弟フィールドから構造をコピーします（label、inputParameter、inputsOnNextNavToAssocScrn、storeOutputAutomatically、styleProperties、isRequired）。記憶を頼りに組み立てないでください。fs-data-capture-reference/SKILL.md のルールでコンポーネントごとの必須項目を確認できますが、デプロイ済みのフローには動作する例があります。
• 新しい choices エントリが必要な場合は、重複を避けてください。 choices 配列に同じ value を持つ選択肢がすでに存在するか確認します。
• 画面コンポーネントに required inputParameter を出力しないでください。 一部の dc* コンポーネント（dcName、dcSignature）では拒否されます。必須かどうかはフィールドの isRequired キーだけで指定します。

6. Tooling PATCH で再デプロイする

編集したフローを新しいドラフトバージョンとして、1回の Tooling API 呼び出しでプッシュします。PATCH /services/data/vXX.0/tooling/sobjects/Flow/<versionId> を次の本文とともにディスパッチします。

{ "Metadata": { "...the full edited Metadata object..." } }

• 部分的なパッチではなく、Metadata オブジェクト全体を送信してください。Tooling はオブジェクト全体を置き換えます。
• 204（No Content）は成功です。400 が返された場合、レスポンス本文の message に Flow の検証エラーが含まれています。ステップ 7 の表を参照して原因を調べてください。
• これにより、フローの新しいドラフトバージョンが作成されます。ユーザーが Flow Builder で新しいドラフトを有効化するまで、既存の有効なバージョンは引き続き実行されます。（保存時に有効化するには、Metadata.status: "Active" を設定します。デフォルトでは Draft のままです。）

7. 結果を報告する

成功した場合：

• 変更内容を明確に伝えます（例：「Header_Information 画面に Notes ShortText フィールドを追加しました」）。
• ユーザーが確認して有効化できるように、Flow Builder の URL を表示します。Tooling API クエリで FlowDefinition Id を調べます。SELECT Id, ActiveVersionId FROM FlowDefinition WHERE DeveloperName = '<FlowApiName>' を指定して GET /services/data/vXX.0/tooling/query をディスパッチし、<instanceUrl>/builder_platform_interaction/flowBuilder.app?flowId=<id> を表示します。
• 有効なバージョンはまだ変更されていないことをユーザーに伝えます。Flow Builder で新しいドラフトを有効化する必要があります。

失敗した場合（PATCH が 400 を返した場合は、レスポンス本文の message からエラーを読み取ります）：

• fs-data-capture-reference/SKILL.md の禁止パターンの表を照合します。編集時によくある原因は、要素配列のグループ化違反、CUD の順序、Element X doesn't exist（参照先の入力ミス）、extension not found（コンポーネント名の誤り）、'Range' is not a valid value（スライダーはサポートされていません）、We can't find this input attribute: 'required'（required inputParameter を削除し、isRequired を使用）です。
• エラーが変更していない要素に関するものなら、取得したフローがすでに壊れた状態だった可能性があります。現在のバージョンの Metadata を再読み込みし、有効なバージョン（GET /tooling/sobjects/Flow/<ActiveVersionId>）と比較してください。
• ユーザーに状況を伝えずに、再試行を2回以上行わないでください。

対象外

• 新しいフローの構築 — fs-data-capture-form-designer + fs-data-capture-form-deployer。
• 多数のフローにまたがる一括移行。
• フローをまったく異なる構造に置き換えること（削除して再構築するほうが簡潔です）。
• processType=DataCaptureFlow ではないフローの編集 — このスキルは FSL Mobile ランタイムを前提としています。

関連スキル

• fs-data-capture-reference（ライブラリ）— 編集のたびに、まずこれを読んでください。有効なフローパターン、禁止パターンと正確なデプロイエラー、見た目を整える HTML、補助的な CustomObject／PermissionSet／CustomTab のデプロイに関する信頼できる情報源です。
• fs-data-capture-form-deployer — このスキルでフローを修正する際に使用する Tooling Flow JSON ラウンドトリップと同じ方法で、フローを作成します。その reference/flow-metadata-json.md は、両スキルにおける Metadata の形式を定める権威ある資料です。

このスキルのファイル

このスキルには実行可能なスクリプトはありません。認証プローブ、フローの取得（GET /tooling/sobjects/Flow/{id}）、再デプロイ（PATCH /tooling/sobjects/Flow/{id}）は、すべて Codey ランタイムを通じて実行する単一の REST 呼び出しです。JSON パッチは、../fs-data-capture-form-deployer/reference/flow-metadata-json.md を参照し、エージェントがインラインで作成します。