platform-agentexchange-partner-offers-configure

トランザクション対応マーケットプレイスのパートナーオファー受信に関する組織設定の有効化

このスキルでは、TransactableMarketplacePrivateOfferSettings Metadata API 型を使用して、enableTransactableMarketplaceReceivePartnerOffers 組織設定を構成します。この設定により、Salesforce 組織がトランザクション対応マーケットプレイス経由でパートナーオファーを受信できるかどうかが制御されます。TM パートナーオファーフローに参加するサブスクライバー組織には、この設定が必要です。

対象範囲

• 対象範囲：設定の現在値の読み取り、Metadata API（TransactableMarketplacePrivateOfferSettings）による有効化または無効化、変更が反映されたことの確認。
• 対象外：パートナーオファーレコードの作成や管理、マーケットプレイスのリスティングの構成、オファー処理に関連する Apex／トリガーの変更。

---

必要な入力

• 対象組織のエイリアスまたはユーザー名：設定を変更する組織です。指定されていない場合は確認してください。
• 希望する状態：true（有効）または false（無効）。デフォルト：true。

---

ワークフロー

フェーズ 1 — 現在の状態を確認する

1. 次を実行して現在の設定値を照会します：

   sf data query -q "SELECT Preference, Value FROM OrgPreference WHERE Preference = 'TransactableMarketplaceReceivePartnerOffers'" --target-org <alias> --use-tooling-api
   

   レコードが存在し、Value = true の場合、設定はすでに有効です。続行する前にユーザーに確認してください。 クエリの結果が 0 行の場合、設定はまだ指定されていません（デフォルトは false です）。

2. 組織のパッケージディレクトリを特定して、メタデータの書き込み先を判断します。次を実行し、その出力を <packageDir> として使用します：

   jq -r '.packageDirectories[0].path // "force-app/main/default"' sfdx-project.json
   

フェーズ 2 — 設定を適用する

3. TransactableMarketplacePrivateOfferSettings メタデータファイルを書き込みます — 正確な XML 構造については assets/org-pref-template.md を読み込み、次の場所にファイルを書き込みます：

   <packageDir>/settings/TransactableMarketplacePrivateOffer.settings
   

   <enableTransactableMarketplaceReceivePartnerOffers>true</enableTransactableMarketplaceReceivePartnerOffers> を設定します（無効にする場合は false）。

4. 対象組織にメタデータをデプロイします。デプロイを実行する前に、ユーザーに確認してください：

   • 対象組織のエイリアスをユーザーに確認済み（誤った組織へのデプロイは簡単には元に戻せません）
   • 希望する状態（true／false）がユーザーの意図と一致していることを確認済み

   sf project deploy start --metadata TransactableMarketplacePrivateOfferSettings --target-org <alias>
   

フェーズ 3 — 確認する

5. ステップ 1 の Tooling API クエリを再実行して変更を確認し、Value 列が希望する状態と一致することを検証します。

6. ユーザーに結果を報告します — 下記の「出力要件」を参照してください。

---

ルール／制約

ルール	理由
メタデータを書き込む前に、必ず現在の値を照会する	不要なデプロイを避け、競合する変更を検出できます
メタデータ型として TransactableMarketplacePrivateOfferSettings を使用する	これはこの設定用にプラットフォームに登録された具体的な型であり、汎用の OrgPreferenceSettings ではありません
設定ファイル名は TransactableMarketplacePrivateOffer.settings にする	Metadata API では、ファイル名が設定ノード名と一致している必要があります
force-app/main/default/ をハードコードしない	実際のパッケージディレクトリを必ず sfdx-project.json から読み取ります
ユーザーに組織のエイリアスを確認せずにデプロイしない	誤った組織へのデプロイは簡単には元に戻せません

---

注意点

問題	解決策
Tooling API のクエリで行が返されない	設定されていません（デフォルトは false です）。新しい設定ファイルを安全に作成できます。
デプロイが INVALID_TYPE で失敗する	メタデータの型名は TransactableMarketplacePrivateOfferSettings です。--metadata フラグの値を確認してください。
デプロイは成功するが、値が変わらない	プロジェクト内の別の設定ファイルがこの設定を上書きしている可能性があります。プロジェクト内でほかの TransactableMarketplacePrivateOffer.settings ファイルを検索してください。
デプロイ時に INSUFFICIENT_ACCESS_OR_READONLY が発生する	デプロイを実行するユーザーには、対象の組織で「Modify All Data」権限、または組織設定の管理者権限が必要です。
UI に設定が表示されない	enableTransactableMarketplaceReceivePartnerOffers は設定 UI に表示されません。確認する唯一の方法は、Tooling API のクエリです。
API バージョン 67.0 以降でのみ利用可能	この型は API v67.0 以降で利用できます。古い API バージョンを指定してデプロイすると失敗します。

---

出力内容

すべてのフェーズを完了したら、次の内容を報告してください。

Org: <alias>
Preference: enableTransactableMarketplaceReceivePartnerOffers
Previous value: <true|false|unset>
New value: <true|false>
File written: <packageDir>/settings/TransactableMarketplacePrivateOffer.settings
Deploy status: Success

---

参照ファイル一覧

ファイル	読み込むタイミング
assets/org-pref-template.md	フェーズ 2、ステップ 3 — 設定ファイルの正確な XML 構造として使用します
examples/org-preference-settings.xml	生成したファイルが想定される形式と一致することを確認するとき