Consumer Goods Promotion Bo API Deploy

Deploy the Promotion BO API

What this does

Turns on the Consumer Goods Cloud TPM Promotion Business Object (BO) API in a Salesforce org, interviews the user for one custom Workflow Step to add to the promotion pipeline, generates and deploys that Apex class, registers it against a BO API entity, wires it into the customer's chosen subset of {create, update, copy} workflows, then proves the whole path end-to-end via three REST endpoints:

• POST /services/apexrest/<prefix>/promotions/initialize
• POST /services/apexrest/<prefix>/promotions/ingest
• GET /services/apexrest/<prefix>/promotions/status?importId=...

It is meant for headless delivery: point it at an org, answer the interview, and the skill installs the step and verifies it. The Promotion BO API ships in the CGCloud managed package (namespace cgcloud released, cgcloud_dev dev/beta). Every Apex identifier, object/field API name, and REST URL is derived from the detected package prefix at runtime — this skill never hard-codes it.

derive is out of scope here (a follow-up skill covers it). Detailed runbooks for the write and smoke phases live under references/:

• references/conventions-and-payload-rules.md — sales-org partitioning, schema-first contract derivation, and the eight cross-workflow payload rules R1–R8.
• references/generate-and-wire.md — Phase 5a (generate + deploy the class) and Phase 5b (register + wire the step), with the full register-step.apex.
• references/smoke-and-verify.md — Phase 6 (contract derivation, payload materialization, create/update/copy legs + verification).
• references/reference-example-set-comment-value.md — the shipped SetCommentValue preset (assets at assets/set-comment-value/).

Inputs to collect first

Ask before starting; do not guess.

1. Org alias — the sf alias of the target org. Required.
2. Sales org — required pre-parameter, default 0001. Must be 4 chars, uppercase (mirrors TPMSetupData.validateSalesOrg). Every downstream lookup (promotion template, tactic template, anchor account, product filter criteria, SKUs) is scoped to this sales org — see references/conventions-and-payload-rules.md ("Sales-org partitioning").
3. Yes to seeding? — Phase 3a fetches the packaged BO API seed and asks for confirmation before inserting ~232 rows across 8 objects. Offer --yes for CI callers.
4. Dry run? — --dry-run runs Phases 1, 2, 3a-preview, the Phase 5 interview, and a validate-only deploy. Writes nothing.

What the customization is gets collected in Phase 5's interview, once the framework state is known.

Find the namespace first

The prefix depends on the installed build — detect it, do not guess. Released package → cgcloud; dev/beta → cgcloud_dev; source-deployed → no prefix.

sf data query --target-org <alias> \
  --query "SELECT NamespacePrefix FROM ApexClass WHERE Name = 'TPMSetupData'" --json

Read records[0].NamespacePrefix and bind three variables used everywhere below:

• PREFIX_DOT — Apex references: cgcloud. / cgcloud_dev. / empty.
• PREFIX_UNDER — object/field API names: cgcloud__ / cgcloud_dev__ / empty.
• URL_NS — REST paths: /cgcloud / /cgcloud_dev / empty.

Every Apex call is ${PREFIX_DOT}ClassName.method(...); every SOQL object/field is ${PREFIX_UNDER}Object__c; every REST URL is /services/apexrest${URL_NS}/promotions/<endpoint>. Substitute at run time.

Phase 1 — Preflight

Run these and stop on the first failure.

1. sf --version; node --version (only if running shipped scripts).
2. sf org display --target-org <alias> --json — confirm reachable, capture instanceUrl + org id (for display/logging only). Every REST call in later phases goes through sf api request rest, which uses the CLI's stored session — this skill never extracts the access token.
3. Validate the sales org locally: length 4, uppercase, non-blank (mirrors TPMSetupData.validateSalesOrg). Fail fast instead of surfacing an Apex stack trace.
4. TPM entitlement (Permission Set License) — the TPM app is licensed through the CGCRetailAndTPMMgmtPsl Permission Set License ("CGC Retail and Trade Promotion Management"); there is no TPM App UserLicense. Check the running user's PSL assignment:

   SELECT Id FROM PermissionSetLicenseAssign
    WHERE Assignee.Username = '<running-user-name>'
      AND PermissionSetLicense.DeveloperName = 'CGCRetailAndTPMMgmtPsl'

   On scratch/dev-hub the PSL may be legitimately unassigned; detect env with SELECT OrganizationType, IsSandbox FROM Organization:
   • OrganizationType = 'Developer Edition' OR IsSandbox = true and empty → warn ("permset gate below is the real check"), continue.
   • Any other org shape and empty → stop ("TPM Permission Set License CGCRetailAndTPMMgmtPsl not assigned to the running user").
5. Running-user permission set (TPM Admin persona) — the setup needs a permission set granting the TPM Master Data Admin persona. The shipped permset is TPM_Master_Data_Admin (packaged; PermissionSet.Name is the bare name regardless of namespace), but customers frequently clone it under their own name — so treat a miss as "ask", not "fail". Take <running-user-name> from sf org display ... .result.username:

   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 → do not hard-fail on the name: show sf org assign permset --name TPM_Master_Data_Admin --target-org <alias> as the default option, but also ask the user to confirm whether they already hold an equivalent (possibly cloned/renamed) permission set for the TPM admin persona. Pause, wait for a cloned-permset confirmation or the assignment, then re-query. Proceed only once admin access is confirmed.
6. Namespace discovery (above).

Phase 2 — Verify BO API framework state

Read-only; tells you whether Phase 3 needs to run. All three counts MUST be scoped to <salesOrg> — the framework rows are sales-org-partitioned.

# 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>'"

• 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 — Preview the default BO API seed (fetch + confirm)

The workflows/steps/junctions/entities/input-structures ship as CSVs inside the packaged TPMSetupData static resource; TPMSetupData.setupBOApi reads and upserts them. Before running it, show the user what will land.

1. Locate the resource:

   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 + expand the resource cross-platform via SFDX — use sf project retrieve, which unpacks a zip StaticResource into a folder on every OS (no curl, no unzip — unzip isn't present on Windows by default). Retrieve into a dedicated setup-data/ subproject so the read-only managed resource never mixes into the Phase-5a deploy tree (./.promotion-bo-api-deploy/force-app, which is what gets deployed back):

   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.
3. SFDX expands the zip to ./.promotion-bo-api-deploy/setup-data/force-app/main/default/staticresources/${PREFIX_UNDER}TPMSetupData/BOApi/. ls it. Expected: 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, 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).
5. Show a summary (row counts per object; total ~232 rows across 8 objects; "upsert on Unique_Key__c — re-running is idempotent"), plus the first 3 rows of 0_BO_API_Workflow__c.csv and 0_BO_API_Workflow_Step__c.csv with {{NS}}/{{SALES_ORG}} substituted.
6. Wait for confirmation unless --yes. "no"/blank → abort clean, point at ./.promotion-bo-api-deploy/setup-data/force-app/main/default/staticresources/${PREFIX_UNDER}TPMSetupData/BOApi/.
7. On --dry-run → stop here; do not run 3b.

Phase 3b — Apply the default seed

Only after 3a confirmation.

1. PHASE3_START=$(date -u +%FT%TZ).
2. Run metadata-wizard setup via anon Apex: ${PREFIX_DOT}TPMSetupData.setupMetadataWizard('<salesOrg>'); → sf apex run --target-org <alias> --file ./.promotion-bo-api-deploy/setup-metadata-wizard.apex.
3. Wait for the whole batch chain. GenericDemoSetupDataBatch self-chains via finish(); polling a single job id misses children. Poll by class:

   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 the child's AsyncApexJob row appearing).
4. Final check — every child succeeded (SELECT Id, Status, NumberOfErrors, ExtendedStatus FROM AsyncApexJob WHERE ApexClass.Name = 'GenericDemoSetupDataBatch' AND CreatedDate >= ${PHASE3_START}). Any Failed/Aborted/NumberOfErrors > 0 → stop, print ExtendedStatus.
5. Repeat 2–4 for ${PREFIX_DOT}TPMSetupData.setupBOApi('<salesOrg>');.