Skip to content

Commit afd1a2d

Browse files
actions-useractions-user
committed
feat: release new skill: platform-agentexchange-partner-offers-enable (PRs #490, #579) @W-23143960@
1 parent b5fba6f commit afd1a2d

3 files changed

Lines changed: 142 additions & 0 deletions

File tree

‎skills/platform-agentexchange-partner-offers-enable/SKILL.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
---
2+
name: platform-agentexchange-partner-offers-enable
3+
description: "Enable or disable the org preference that controls whether a Salesforce org can receive partner offers from the Transactable Marketplace. Use this skill when the user wants to turn partner offer reception on or off for an org. TRIGGER when: user asks to enable or disable partner offers, configure TransactableMarketplaceReceivePartnerOffers, configure enableTransactableMarketplaceReceivePartnerOffers, set up marketplace partner offer reception, toggle the TM partner offers setting, edit a TransactableMarketplacePrivateOffer.settings file, or configure org preferences related to transactable marketplace. DO NOT TRIGGER when: user needs to create or manage the partner offer records themselves, configure marketplace listing settings, or work with SfdcPartnerOffer objects (use deploying-metadata or generating-apex instead)."
4+
metadata:
5+
version: "1.0"
6+
minApiVersion: "67.0"
7+
---
8+
9+
# Enabling Transactable Marketplace Receive Partner Offers Org Preference
10+
11+
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.
12+
13+
## Scope
14+
15+
- **In scope**: Reading the current value of the pref, enabling or disabling it via Metadata API (`TransactableMarketplacePrivateOfferSettings`), and verifying the change took effect.
16+
- **Out of scope**: Creating or managing partner offer records, configuring marketplace listings, or any Apex/trigger changes related to offer processing.
17+
18+
---
19+
20+
## Required Inputs
21+
22+
- **Target org alias or username**: The org where the pref should be set. Ask if not provided.
23+
- **Desired state**: `true` (enable) or `false` (disable). Default: `true`.
24+
25+
---
26+
27+
## Workflow
28+
29+
### Phase 1 — Check current state
30+
31+
1. **Query the current preference value** by running:
32+
```bash
33+
sf data query -q "SELECT Preference, Value FROM OrgPreference WHERE Preference = 'TransactableMarketplaceReceivePartnerOffers'" --target-org <alias> --use-tooling-api
34+
```
35+
If the record exists and `Value = true`, the pref is already enabled — confirm with the user before proceeding.
36+
If the query returns no rows, the pref is not yet set (defaults to `false`).
37+
38+
2. **Resolve the org's package directory** to determine where to write metadata. Run this and use its output as `<packageDir>`:
39+
```bash
40+
jq -r '.packageDirectories[0].path // "force-app/main/default"' sfdx-project.json
41+
```
42+
43+
### Phase 2 — Apply the preference
44+
45+
3. **Write the TransactableMarketplacePrivateOfferSettings metadata file** — load `assets/org-pref-template.md` for the exact XML structure, then write the file at:
46+
```text
47+
<packageDir>/settings/TransactableMarketplacePrivateOffer.settings
48+
```
49+
Set `<enableTransactableMarketplaceReceivePartnerOffers>true</enableTransactableMarketplaceReceivePartnerOffers>` (or `false` if disabling).
50+
51+
4. **Deploy the metadata** to the target org. Before running the deploy, confirm with the user:
52+
- [ ] Confirmed the target org alias with the user (deploying to the wrong org is not easily reversible)
53+
- [ ] Confirmed the desired state (`true`/`false`) matches the user's intent
54+
```bash
55+
sf project deploy start --metadata TransactableMarketplacePrivateOfferSettings --target-org <alias>
56+
```
57+
58+
### Phase 3 — Verify
59+
60+
5. **Confirm the change** by re-running the Tooling API query from step 1 and verifying the `Value` column matches the desired state.
61+
62+
6. **Report to the user** — see Output Expectations below.
63+
64+
---
65+
66+
## Rules / Constraints
67+
68+
| Rule | Rationale |
69+
|------|-----------|
70+
| Always query the current value before writing metadata | Avoids unnecessary deploys and detects conflicting changes |
71+
| Use `TransactableMarketplacePrivateOfferSettings` as the metadata type | This is the concrete type registered in the platform for this pref, not the generic `OrgPreferenceSettings` |
72+
| The settings file must be named `TransactableMarketplacePrivateOffer.settings` | Metadata API requires the filename to match the settings node name |
73+
| Do not hardcode `force-app/main/default/` | Always read `sfdx-project.json` for the actual package directory |
74+
| Never deploy without confirming the org alias with the user | Deploying to the wrong org is not easily reversible |
75+
76+
---
77+
78+
## Gotchas
79+
80+
| Issue | Resolution |
81+
|-------|------------|
82+
| Tooling API query returns no rows | Pref is unset (defaults to `false`). Safe to create a new settings file. |
83+
| Deploy fails with `INVALID_TYPE` | The metadata type name is `TransactableMarketplacePrivateOfferSettings` — check the `--metadata` flag value. |
84+
| 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. |
85+
| `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. |
86+
| Pref not visible in UI | `enableTransactableMarketplaceReceivePartnerOffers` is not surfaced in Setup UI — the Tooling API query is the only way to verify it. |
87+
| Available from API version 67.0+ only | The type is available from API v67.0 — deploying against an older API version will fail. |
88+
89+
---
90+
91+
## Output Expectations
92+
93+
After completing all phases, report:
94+
95+
```text
96+
Org: <alias>
97+
Preference: enableTransactableMarketplaceReceivePartnerOffers
98+
Previous value: <true|false|unset>
99+
New value: <true|false>
100+
File written: <packageDir>/settings/TransactableMarketplacePrivateOffer.settings
101+
Deploy status: Success
102+
```
103+
104+
---
105+
106+
## Reference File Index
107+
108+
| File | When to read |
109+
|------|-------------|
110+
| `assets/org-pref-template.md` | Phase 2, step 3 — use as the exact XML structure for the settings file |
111+
| `examples/org-preference-settings.xml` | To verify the generated file matches expected format |

‎skills/platform-agentexchange-partner-offers-enable/assets/org-pref-template.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# TransactableMarketplacePrivateOfferSettings XML Template
2+
3+
Use this exact structure when writing the settings metadata file.
4+
5+
## File path
6+
7+
```text
8+
<packageDir>/settings/TransactableMarketplacePrivateOffer.settings
9+
```
10+
11+
## Template
12+
13+
```xml
14+
<?xml version="1.0" encoding="UTF-8"?>
15+
<TransactableMarketplacePrivateOfferSettings xmlns="http://soap.sforce.com/2006/04/metadata">
16+
<enableTransactableMarketplaceReceivePartnerOffers>true</enableTransactableMarketplaceReceivePartnerOffers>
17+
</TransactableMarketplacePrivateOfferSettings>
18+
```
19+
20+
Replace `true` with `false` to disable.
21+
22+
## Notes
23+
24+
- The metadata type is `TransactableMarketplacePrivateOfferSettings`, available from API version 67.0+.
25+
- This type is registered with `apiCreateAllowed="false"` and `apiDeleteAllowed="false"` — it can only be updated, not created or deleted via the API. This does NOT mean you should skip writing the file: the preference always exists in the org with a default value, so writing a new local settings file and deploying it is treated as an update by the Metadata API and is always valid.
26+
- The `xmlns` attribute is required; omitting it causes a deploy parse error.
27+
- The field name is `enableTransactableMarketplaceReceivePartnerOffers` (note the `enable` prefix).

‎skills/platform-agentexchange-partner-offers-enable/examples/org-preference-settings.xml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<TransactableMarketplacePrivateOfferSettings xmlns="http://soap.sforce.com/2006/04/metadata">
3+
<enableTransactableMarketplaceReceivePartnerOffers>true</enableTransactableMarketplaceReceivePartnerOffers>
4+
</TransactableMarketplacePrivateOfferSettings>

0 commit comments

Comments
 (0)