Deploy a Unified Catalog Service Process Template

Deploy a specific Unified Catalog Service Process template into the org with the Salesforce CLI (sf api request rest). The template becomes a published Product2-backed Service Process with its dependency flows wired in. This skill uses a deterministic gate, not a chat confirmation: it deploys only a template the user explicitly named, only after re-resolving that name to exactly one live template, and it verifies by re-reading afterward. If the name is missing, ambiguous, or unmatched, it stops and reports — it never guesses which template to deploy.

Scope

• In scope: Resolving a named template against the live catalog; building the deploy payload from the template's dependency metadata; deploying one template; verifying the deployment.
• Out of scope: Searching / browsing / comparing templates (→ service-catalog-template-search); deploying more than one template at once (bulk); activating or publishing beyond what deploy does; editing templates; Data Cloud data kits; CRM Analytics / App Framework templates.

The deterministic gate (why there is no confirm prompt)

This is a write skill, but its confirm-to-write contract is a deterministic validation gate, not an interactive prompt. A deploy proceeds only when ALL of these hold:

1. The user's own message is an explicit deploy imperative for a named template ("deploy the Reset Account Password template"), not a browse/search/compare request.
2. That name, matched case-insensitively against the freshly re-fetched catalog, resolves to exactly one template. Zero matches → stop with the candidate list. Two or more → stop with the matches and ask the user to disambiguate by exact name. Never pick the first.
3. The deploy route is reachable at the targeted API version (v67.0; the route does not exist below v65.0) and the current user has Unified Catalog access — established by the preflight access check in Phase 0, which self-heals a missing assignment before the run continues.

If any condition fails, stop and report — do not deploy. The explicit named imperative plus the exact-one-match resolution IS the confirmation; there is nothing to prompt for — this keeps the write path deterministic and eval-able rather than gated on an unanswerable dialog.

Preflight access check (Phase 0) — behavior-based, self-healing

Unified Catalog access is per-user. The Phase 2 catalog GET is the access probe — do not pre-check with SOQL or branch on persona names. Accept whatever already yields 200 (access can come from UnifiedCatalogAdmin, UnifiedCatalogAgent, UnifiedCatalogCommunityUser, or any equivalent set the user holds); self-heal only on 403:

• HTTP 200 → access present; continue, assign nothing.
• 403 + FUNCTIONALITY_NOT_ENABLED [ServiceAutomationFamily] → sf org assign permsetlicense --name UnifiedCatalogAdminPsl, then sf org assign permset --name UnifiedCatalogAdmin, then re-probe once. Now 200 → continue. Still 403 → the org lacks the license itself (not user-fixable) — report and stop; never loop.

The re-probe GET is the arbiter, not the assign command's exit status. A Duplicate PermissionSetAssignment failure (when the user is already assigned) is benign — judge success solely by the re-probe 200, not by what the assign printed. UnifiedCatalogAdmin is the verified-sufficient heal target — there is no "Designer" set. See references/cli-invocation.md → Step 0 for the full recipe.

Routes at a glance

All run through sf api request rest. Full command shapes live in references/cli-invocation.md.

Response: sf api request rest prints the raw Connect body (no {status_code, body} wrapper). The deploy response is top-level { deploymentResult, status, templateId }, where status is SUCCESS or FAILURE. It is synchronous — no job id to poll; verify by re-reading. Add -i to read the HTTP status line. Pinned to v67.0 (the routes do not exist below v65.0).

Required Inputs

Send only the fields the user supplied — omit optional keys entirely rather than sending empty values.

Workflow

Sequential. Read before you write; verify after you write. Every call runs through sf api request rest.

Phase 1 — Entry check

1. Confirm entry conditions — there must be an explicit deploy imperative and a named template. If the user has not named a template (still browsing), stop and redirect to service-catalog-template-search. Do not deploy from a vague request.

Phase 2 — Resolve the template + preflight access (the gate)

2. Re-fetch the catalog (this GET is also the access probe) and classify with the resolver script. Run the read-only GET with -i (so the HTTP status line is captured), save the raw output, then let scripts/resolve-template.mjs do the deterministic status-parsing and name resolution — the HTTP 200/403/404/empty branching and the case-insensitive match count are a fixed algorithm, not a judgment call (authoring standard A9):

   sf api request rest \
     '/services/data/v67.0/connect/service-automation/service-process/get-all-templates' \
     --method GET -i > /tmp/uc-get.txt
   node "<skill_dir>/scripts/resolve-template.mjs" /tmp/uc-get.txt "<the exact template name the user named>"
   

   Copy

   Act on the script's action:

   • SELF_HEAL (403 FUNCTIONALITY_NOT_ENABLED) → run the Phase 0 self-heal: sf org assign permsetlicense --name UnifiedCatalogAdminPsl, then sf org assign permset --name UnifiedCatalogAdmin, then re-run the GET + resolver once. Now action ≠ SELF_HEAL → continue on the new action. Still SELF_HEAL → the org lacks the license itself (not user-fixable) — report and stop (STOPPED_NO_ACCESS). Never loop the heal.
   • STOP_ROUTE (404 NOT_FOUND) → the route is below its minimum API version (this skill targets v67.0; it does not exist below v65.0) — report and stop.
   • STOP_OTHER (any other non-200: 401 / 429 / 5xx, or an unreadable body) → the catalog read failed (API, auth, or transport error) — report the HTTP status and stop (STOPPED_OTHER). This is not an empty catalog or a missing template; never deploy or report name-not-found on a failed read.
   • STOP_EMPTY → catalog empty; nothing to deploy; stop.
   • DEPLOY (exactly one exact-name match) → the script returns resolved.id and resolved.templateDependencyMetadata; proceed to Phase 3.
   • STOP_AMBIGUOUS (two or more matches) → stop; list availableNames and ask the user to name the exact one. Never pick the first. This covers both a genuine multi-exact tie and a category term (e.g. "access") that isn't itself a template name but appears in ≥2 template names — the request is ambiguous, not simply missing, so matchCount is the candidate count.
   • STOP_NOT_FOUND (zero matches, and fewer than two near-matches) → stop; report the requested name and list availableNames. Do not deploy a near-match.

   Always re-resolve from this live fetch — never trust an Id, description, or payload carried over from a prior search turn (it may be stale or spoofed). The resolver reads only the fresh GET output.

Phase 3 — Build & deploy

3. Collect deployment inputs if required — if any dependency has requiresDeploymentInput: true and the user has not supplied the needed values, ask for them now. (This is a data-gathering question, not a confirm-to-deploy prompt.)

4. Build the deploy body with the payload script. Transforming templateDependencyMetadata into flowTemplates[] — one element per dependency, enum values passed through verbatim (SCREAMING_SNAKE_CASE), primary keys with defined fallbacks — is a fixed transformation, so it runs in scripts/build-deploy-payload.mjs rather than in prose (authoring standard A9). It never title-cases or hardcodes an enum, and merges only the optional fields the user actually supplied:

   # /tmp/uc-get.txt is the resolver output from Phase 2 (carries resolved.templateDependencyMetadata);
   # /tmp/uc-optional.json (optional) holds only user-supplied keys: description / isActive /
   # deploymentMode / catalog / category / serviceProcessName.
   node "<skill_dir>/scripts/build-deploy-payload.mjs" \
     <(node "<skill_dir>/scripts/resolve-template.mjs" /tmp/uc-get.txt "<template name>") \
     /tmp/uc-optional.json > /tmp/uc-deploy-body.json
   

   Copy

   The script builds flowTemplates[] from the live metadata — never ask the user for flow API names.

5. Deploy — POST /connect/service-automation/template/deploy/{id} with the script-built body:

   sf api request rest \
     '/services/data/v67.0/connect/service-automation/template/deploy/<templateId>' \
     --method POST \
     --body @/tmp/uc-deploy-body.json
   

   Copy

   Read the top-level status. On FAILURE or a 403, surface the exact error and stop — a 403 (FUNCTIONALITY_NOT_ENABLED) means the org/user lacks Unified Catalog deploy access. See the serviceProcessName drift note in Gotchas before retrying a rejected body.

Phase 4 — Activate, verify & report

6. Activate and verify with the activate-verify script. The deploy POST lands the Product2 with IsActive=false; a deployed catalog item must end up active. The serviceProcessName is user-supplied, so it must never be interpolated into a Bash command or a SOQL literal — scripts/activate-verify.mjs takes the name as an argument (no shell interpolation), escapes it for SOQL, and invokes sf with an argument array. It resolves the new Product2 by name, activates it, and re-reads to confirm — the resolve→activate→verify sequence is fixed conditional DML, so it runs in the script, not in prose (Agent Safety + authoring standard A9):

   # pass the name as an argument — the script never builds a shell/SOQL string from it.
   # add --no-activate only if the user explicitly wants the Service Process left inactive.
   node "<skill_dir>/scripts/activate-verify.mjs" "<serviceProcessName>" --target-org <alias>
   

   Copy

   The script prints { found, id, isActive, activated, verified }. Report success only when verified is true (the re-read confirms the Service Process exists and, unless --no-activate, is active). Do not trust the POST response alone.

7. Report using the output format below. Present template and Service Process names, never Ids.

Rules / Constraints

Gotchas

Highest-risk pitfalls only (10). Full coverage — auth errors, template-level type, requiresDeploymentInput, etc. — lives in references/cli-invocation.md.

Verification Checklist

• Did the user explicitly name a template with a deploy imperative (else redirect to search)?
• Did the GET probe return 200 — or, on 403, did the skill self-heal (PSL and permset) and re-probe once, stopping if still 403?
• Was the catalog re-fetched live and the name resolved to exactly one template (not a carried-over Id) — stopping rather than guessing on zero or multiple matches?
• Was flowTemplates[] built from templateDependencyMetadata with enums echoed verbatim (SCREAMING_SNAKE), and no flow API names asked of the user?
• Was the deploy dispatched once, then the Product2 activated (IsActive=true, unless left inactive) and confirmed by a re-read — not the POST response alone?
• Were only names (no raw Ids) shown to the user?

Output Format

On failure (no name / no match / ambiguous / deploy error / no access / wrong API version): state the exact condition and stop. For ambiguity or no-match, list the available template names.

On success:

Unified Catalog Template Deployed (via service-catalog-template-deploy)

Template:         <Template Name>
Service Process:  <serviceProcessName>
Active:           yes  (Product2 IsActive=true)
Access:           <already had access | assigned UnifiedCatalogAdmin to enable>
Catalog/Category: <values, if set>
Dependencies:     <N> flow template(s) deployed
Verified:         re-read confirms the Service Process exists and is active

No record Ids in user-facing output — use human-readable names only.

Reference File Index

Related Skills