platform-agentexchange-partner-offers-configure

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Enabling Transactable Marketplace Receive Partner Offers Org Preference

启用Transactable Marketplace接收合作伙伴优惠的组织偏好

This skill configures the

enableTransactableMarketplaceReceivePartnerOffers

org preference via the

TransactableMarketplacePrivateOfferSettings

Metadata API type, which controls whether a Salesforce org is eligible to receive partner offers through the Transactable Marketplace. It is required for subscriber orgs that participate in the TM partner offer flow.

此技能通过

TransactableMarketplacePrivateOfferSettings

元数据API类型配置

enableTransactableMarketplaceReceivePartnerOffers

组织偏好，该偏好控制Salesforce组织是否有资格通过Transactable Marketplace接收合作伙伴优惠。参与TM合作伙伴优惠流程的订阅组织需要设置此偏好。

Scope

适用范围

In scope: Reading the current value of the pref, enabling or disabling it via Metadata API (
```
TransactableMarketplacePrivateOfferSettings
```
), and verifying the change took effect.
Out of scope: Creating or managing partner offer records, configuring marketplace listings, or any Apex/trigger changes related to offer processing.

包含范围：读取偏好的当前值、通过元数据API（
```
TransactableMarketplacePrivateOfferSettings
```
）启用或禁用该偏好，并验证更改是否生效。
排除范围：创建或管理合作伙伴优惠记录、配置市场列表设置，或任何与优惠处理相关的Apex/触发器更改。

Required Inputs

必要输入

Target org alias or username: The org where the pref should be set. Ask if not provided.
Desired state:
```
true
```
(enable) or
```
false
```
(disable). Default:
```
true
```
.

目标组织别名或用户名：需要设置偏好的组织。若未提供，请询问用户。
期望状态：
```
true
```
（启用）或
```
false
```
（禁用）。默认值：
```
true
```
。

Workflow

工作流程

Phase 1 — Check current state

阶段1 — 检查当前状态

Query the current preference value by running:
bash
```
sf data query -q "SELECT Preference, Value FROM OrgPreference WHERE Preference = 'TransactableMarketplaceReceivePartnerOffers'" --target-org <alias> --use-tooling-api
```
If the record exists and
```
Value = true
```
, the pref is already enabled — confirm with the user before proceeding. If the query returns no rows, the pref is not yet set (defaults to
```
false
```
).
Resolve the org's package directory to determine where to write metadata. Run this and use its output as
```
<packageDir>
```
:
bash
```
jq -r '.packageDirectories[0].path // "force-app/main/default"' sfdx-project.json
```

查询当前偏好值，运行以下命令：
bash
```
sf data query -q "SELECT Preference, Value FROM OrgPreference WHERE Preference = 'TransactableMarketplaceReceivePartnerOffers'" --target-org <alias> --use-tooling-api
```
如果记录存在且
```
Value = true
```
，则该偏好已启用 — 继续操作前请与用户确认。如果查询无结果，则该偏好尚未设置（默认值为
```
false
```
）。
解析组织的包目录以确定元数据的写入位置。运行以下命令并将输出作为
```
<packageDir>
```
：
bash
```
jq -r '.packageDirectories[0].path // "force-app/main/default"' sfdx-project.json
```

Phase 2 — Apply the preference

阶段2 — 应用偏好设置

Write the TransactableMarketplacePrivateOfferSettings metadata file — load

assets/org-pref-template.md

for the exact XML structure, then write the file at:

text

<packageDir>/settings/TransactableMarketplacePrivateOffer.settings

Set

<enableTransactableMarketplaceReceivePartnerOffers>true</enableTransactableMarketplaceReceivePartnerOffers>

(or

false

if disabling).

Deploy the metadata to the target org. Before running the deploy, confirm with the user:
- Confirmed the target org alias with the user (deploying to the wrong org is not easily reversible)
- Confirmed the desired state (
```
true
```
  /
```
false
```
  ) matches the user's intent
bash
```
sf project deploy start --metadata TransactableMarketplacePrivateOfferSettings --target-org <alias>
```

写入TransactableMarketplacePrivateOfferSettings元数据文件 — 加载

assets/org-pref-template.md

获取精确的XML结构，然后将文件写入以下路径：

text

<packageDir>/settings/TransactableMarketplacePrivateOffer.settings

设置

<enableTransactableMarketplaceReceivePartnerOffers>true</enableTransactableMarketplaceReceivePartnerOffers>

（若禁用则设为

false

）。

将元数据部署到目标组织。运行部署前，请与用户确认：
- 已与用户确认目标组织别名（部署到错误组织后难以撤销）
- 已确认期望状态（
```
true
```
  /
```
false
```
  ）与用户意图一致
bash
```
sf project deploy start --metadata TransactableMarketplacePrivateOfferSettings --target-org <alias>
```

Phase 3 — Verify

阶段3 — 验证

Confirm the change by re-running the Tooling API query from step 1 and verifying the
```
Value
```
column matches the desired state.
Report to the user — see Output Expectations below.

确认更改生效，重新运行阶段1中的工具API查询，验证
```
Value
```
列与期望状态一致。
向用户报告结果 — 请参阅下方的输出要求。

Rules / Constraints

规则 / 约束

Rule	Rationale
Always query the current value before writing metadata	Avoids unnecessary deploys and detects conflicting changes
Use `TransactableMarketplacePrivateOfferSettings` as the metadata type	This is the concrete type registered in the platform for this pref, not the generic `OrgPreferenceSettings`
The settings file must be named `TransactableMarketplacePrivateOffer.settings`	Metadata API requires the filename to match the settings node name
Do not hardcode `force-app/main/default/`	Always read `sfdx-project.json` for the actual package directory
Never deploy without confirming the org alias with the user	Deploying to the wrong org is not easily reversible

规则	理由
写入元数据前始终查询当前值	避免不必要的部署，检测冲突更改
使用 `TransactableMarketplacePrivateOfferSettings` 作为元数据类型	这是平台为此偏好注册的具体类型，而非通用的 `OrgPreferenceSettings`
设置文件必须命名为 `TransactableMarketplacePrivateOffer.settings`	元数据API要求文件名与设置节点名称匹配
不要硬编码 `force-app/main/default/`	始终读取 `sfdx-project.json` 获取实际的包目录
未与用户确认组织别名前绝不部署	部署到错误组织后难以撤销

Gotchas

常见问题

Issue	Resolution
Tooling API query returns no rows	Pref is unset (defaults to `false` ). Safe to create a new settings file.
Deploy fails with `INVALID_TYPE`	The metadata type name is `TransactableMarketplacePrivateOfferSettings` — check the `--metadata` flag value.
Deploy succeeds but value doesn't change	Another settings file in the project may be overriding this one. Search for other `TransactableMarketplacePrivateOffer.settings` files in the project.
`INSUFFICIENT_ACCESS_OR_READONLY` on deploy	User running the deploy must have the "Modify All Data" or org preference admin permission in the target org.
Pref not visible in UI	`enableTransactableMarketplaceReceivePartnerOffers` is not surfaced in Setup UI — the Tooling API query is the only way to verify it.
Available from API version 67.0+ only	The type is available from API v67.0 — deploying against an older API version will fail.

问题	解决方法
工具API查询无结果	偏好未设置（默认值为 `false` ）。可以安全创建新的设置文件。
部署失败并提示 `INVALID_TYPE`	元数据类型名称为 `TransactableMarketplacePrivateOfferSettings` — 检查 `--metadata` 参数的值。
部署成功但值未更改	项目中可能存在其他设置文件覆盖了此设置。搜索项目中的其他 `TransactableMarketplacePrivateOffer.settings` 文件。
部署时提示 `INSUFFICIENT_ACCESS_OR_READONLY`	执行部署的用户必须在目标组织中拥有“修改所有数据”或组织偏好管理员权限。
偏好在UI中不可见	`enableTransactableMarketplaceReceivePartnerOffers` 未在设置UI中显示 — 工具API查询是验证它的唯一方式。
仅支持API版本67.0+	该类型仅在API v67.0及以上版本可用 — 针对旧API版本部署会失败。

Output Expectations

输出要求

After completing all phases, report:

text

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

完成所有阶段后，报告以下内容：

text

组织: <alias>
偏好: enableTransactableMarketplaceReceivePartnerOffers
之前的值: <true|false|未设置>
新值: <true|false>
写入文件: <packageDir>/settings/TransactableMarketplacePrivateOffer.settings
部署状态: 成功

Reference File Index

参考文件索引

File	When to read
`assets/org-pref-template.md`	Phase 2, step 3 — use as the exact XML structure for the settings file
`examples/org-preference-settings.xml`	To verify the generated file matches expected format

文件	读取时机
`assets/org-pref-template.md`	阶段2，步骤3 — 用作设置文件的精确XML结构
`examples/org-preference-settings.xml`	验证生成的文件是否符合预期格式