forcedotcom/sf-skills / skills/consumer-goods-promotion-bo-api-deploy
consumer-goods-promotion-bo-api-deploy
VerifiedUse to enable the Consumer Goods Cloud TPM Promotion Business Object (BO) API framework in a Salesforce org, interview the user for the custom Workflow Step they want to add, generate and deploy that Apex class, wire it into the create/update/copy workflows, and prove it end-to-end via headless REST ingest. Ships a worked reference example (SetCommentValue) but the customization is user-supplied per org. Triggers on "deploy the promotion BO API", "set up promotion BO API", "headless promotion create", "add a BO API workflow step".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 17.9 KB |
| assets/set-comment-value/README.md | markdown | 1.1 KB |
| assets/set-comment-value/SetCommentValue.cls | other | 3.0 KB |
| assets/set-comment-value/SetCommentValue.cls-meta.xml | config | 174 B |
| assets/set-comment-value/interview-answers.json | config | 363 B |
| assets/set-comment-value/payloads/copy.json | config | 166 B |
| assets/set-comment-value/payloads/create.json | config | 458 B |
| assets/set-comment-value/payloads/update.json | config | 326 B |
| references/conventions-and-payload-rules.md | markdown | 20.3 KB |
| references/generate-and-wire.md | markdown | 13.8 KB |
| references/preflight-and-seed-queries.md | markdown | 6.2 KB |
| references/reference-example-set-comment-value.md | markdown | 4.7 KB |
| references/smoke-and-verify.md | markdown | 14.4 KB |
references/preflight-and-seed-queries.md
View on GitHub# Preflight + seed queries (Phases 1–3b)
Load-bearing SOQL and shell recipes that `SKILL.md` Phases 1–3b hand off to.
`PREFIX_DOT` / `PREFIX_UNDER` / `URL_NS` come from `SKILL.md` "Find the
namespace first". Every query is **sales-org-scoped** where the underlying
object is partitioned.
## Phase 1 — Preflight queries
### Step 4: TPM entitlement (Permission Set License)
TPM is licensed via the `CGCRetailAndTPMMgmtPsl` PSL (no `TPM App`
UserLicense):
```sql
SELECT Id FROM PermissionSetLicenseAssign
WHERE Assignee.Username = '<running-user-name>'
AND PermissionSetLicense.DeveloperName = 'CGCRetailAndTPMMgmtPsl'
```
Empty + `OrganizationType = 'Developer Edition'` or `IsSandbox = true` →
**warn** (the permset gate below is the real check); any other org shape +
empty → **stop**.
### Step 5: Running-user permission set (TPM Admin persona)
Need a permset granting the *TPM Master Data Admin* persona. The shipped name
is `TPM_Master_Data_Admin` (bare, non-namespaced), but customers frequently
clone it; treat a miss as "ask", not "fail":
```sql
SELECT PermissionSet.Name, PermissionSet.Label FROM PermissionSetAssignment
WHERE Assignee.Username = '<running-user-name>'
AND (PermissionSet.Name = 'TPM_Master_Data_Admin'
OR PermissionSet.Label LIKE '%TPM%Master Data Admin%')
```
Match → proceed. No match → offer
`sf org assign permset --name TPM_Master_Data_Admin --target-org <alias>` AND
ask if the user holds an equivalent (cloned/renamed) permset; wait for
confirmation or assignment, then re-query. Proceed only once admin access is
confirmed.
### Step 7: Running user's `Sales_Org__c` matches `<salesOrg>`
```sql
SELECT Id, Username, ${PREFIX_UNDER}Sales_Org__c FROM User WHERE Username = '<running-user-name>'
```
Blank or `!= '<salesOrg>'` → stop; fix on the user record (confirm before
mutating). This gate is R6 of `conventions-and-payload-rules.md` — blank
throws `SOU0003`, mismatch surfaces as "not found" (create/update) or
`TransformationError` (copy). Category access is preflighted in Phase 6 per
R9.
## Phase 2 — Verify BO API framework state
Read-only. All three counts MUST be scoped to `<salesOrg>` — the framework
rows are sales-org-partitioned.
```bash
# 1. Workflow rows for this sales org (expect 4: create/update/copy/derive)
sf data query --target-org <alias> --json --query "
SELECT Name FROM ${PREFIX_UNDER}BO_API_Workflow__c
WHERE ${PREFIX_UNDER}BO_API__r.Name = 'Promotion'
AND ${PREFIX_UNDER}BO_API__r.${PREFIX_UNDER}Sales_Org__c = '<salesOrg>'"
# 2. Step rows for this sales org
sf data query --target-org <alias> --json --query "
SELECT COUNT(Id) FROM ${PREFIX_UNDER}BO_API_Workflow_Step__c
WHERE ${PREFIX_UNDER}Sales_Org__c = '<salesOrg>'"
# 3. Junction rows whose parent workflow belongs to a Promotion BO API for this sales org
sf data query --target-org <alias> --json --query "
SELECT COUNT(Id) FROM ${PREFIX_UNDER}BO_API_Workflow_Workflow_Step__c
WHERE ${PREFIX_UNDER}BO_API_Workflow__r.${PREFIX_UNDER}BO_API__r.Name = 'Promotion'
AND ${PREFIX_UNDER}BO_API_Workflow__r.${PREFIX_UNDER}BO_API__r.${PREFIX_UNDER}Sales_Org__c = '<salesOrg>'"
```
Outcome routing:
- Zero workflow rows → fresh for this sales org, Phase 3 will seed.
- Full state (4 workflow rows `create/update/copy/derive`; >0 step + junction
rows) → Phase 3 is a no-op for this sales org (still run for idempotency;
3a shows zero net-new).
- Partial state → **error**; stop, report which rows are missing. A human
inspects first.
## Phase 3a — Retrieve the packaged seed
Fetch the `TPMSetupData` static resource into a dedicated `setup-data/`
subproject (keeps the read-only managed resource out of the Phase-5a deploy
tree at `./.promotion-bo-api-deploy/force-app`).
1. Locate the resource:
```bash
sf data query --target-org <alias> --json --query "
SELECT Id, Name, NamespacePrefix, SystemModStamp, BodyLength
FROM StaticResource WHERE Name = 'TPMSetupData'"
```
Zero rows → stop ("TPMSetupData static resource not found — is the CGCloud
package installed?"). Multiple rows → prefer the one whose
`NamespacePrefix` matches Phase 1; if prefixes disagree, stop and ask.
2. Retrieve into the dedicated subproject:
```bash
mkdir -p ./.promotion-bo-api-deploy/setup-data/force-app/main/default
printf '{ "packageDirectories": [{ "path": "force-app", "default": true }], "sourceApiVersion": "60.0" }' \
> ./.promotion-bo-api-deploy/setup-data/sfdx-project.json
( cd ./.promotion-bo-api-deploy/setup-data && sf project retrieve start \
--metadata "StaticResource:${PREFIX_UNDER}TPMSetupData" --target-org <alias> --json )
```
Non-success → stop, print `result` errors. (`sf project retrieve` works
cross-platform; no `unzip` needed.)
3. SFDX expands the zip to
`./.promotion-bo-api-deploy/setup-data/force-app/main/default/staticresources/${PREFIX_UNDER}TPMSetupData/BOApi/`.
Expected 8 CSVs — `0_BO_API__c.csv`, `0_BO_API_Entity__c.csv`,
`0_BO_API_Output_Entity__c.csv`, `0_BO_API_Workflow__c.csv`,
`0_BO_API_Workflow_Entity__c.csv`, `0_BO_API_Workflow_Step__c.csv`,
`0_BO_API_Workflow_Workflow_Step__c.csv`,
`0_BO_API_Step_Input_Structure__c.csv` — plus `import.json`. Any missing →
stop, print the delta.
4. Confirm each target sObject exists:
`sf sobject describe --sobject '${PREFIX_UNDER}BO_API_Workflow__c' --target-org <alias> > /dev/null`
(etc.). Any describe failure → stop (package partially installed).
## Phase 3b — Poll the batch chain
`GenericDemoSetupDataBatch` self-chains via `finish()`, so poll by class (not
by a single job id):
```bash
sf data query --target-org <alias> --json --query "
SELECT COUNT() FROM AsyncApexJob
WHERE ApexClass.Name = 'GenericDemoSetupDataBatch'
AND CreatedDate >= ${PHASE3_START}
AND Status NOT IN ('Completed','Failed','Aborted')"
```
Sleep 5s between polls; break when count is zero for **two consecutive** polls
(covers the gap between a parent's `finish()` and a child's `AsyncApexJob` row
appearing).
Final check — every child succeeded:
```sql
SELECT Id, Status, NumberOfErrors, ExtendedStatus FROM AsyncApexJob
WHERE ApexClass.Name = 'GenericDemoSetupDataBatch' AND CreatedDate >= ${PHASE3_START}
```
Any `Failed`/`Aborted`/`NumberOfErrors > 0` → stop, print `ExtendedStatus`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |