Assign an ITSM Fulfiller Persona Permission Set (Prompt-Template Access)

Grants the running user one of the Core-shipped Fulfiller persona permission sets that expose the svc_itsm_intelligence__* prompt-template invocable actions on the target org — the actions the Fulfiller NGA agent scripts reference via source: / target: generatePromptResponse://.... When those invocables are not surfaced by /services/data/v67.0/actions/custom/generatePromptResponse for the running user, the Fulfiller agent-configure skill's Phase 6 activate call returns HTTP 200 with a silent {success:false, messages:[{... "does not exist"}]} body and the agent never becomes usable. This skill fixes that gap by assigning the correct Fulfiller persona permset (and its backing license when one exists) — or, when no Fulfiller persona permset is provisioned on the org at all, hands off to the Agentforce Studio configure/validate skill so the ITSM AddOn(s) can be enabled first.

The three Fulfiller persona permsets, their AddOns, PSLs, and the userPerms they grant are documented in references/permset-topology.md. All are Core-shipped in namespace force — there is no managed-package namespaced permset for this feature.

Employee agent is out of scope. The Employee NGA agent's access model is separate (org-preferences + a different persona layer) and does not map onto these three persona permsets.

Every call runs through the Salesforce CLI (sf):

• sf api request rest — authenticated Connect API GET (identity, verify read).
• sf data query — SOQL on PermissionSet (persona presence), PermissionSetAssignment / PermissionSetLicenseAssign (idempotency).
• sf org assign permset — assigning the permission set for the running user.
• No token is ever extracted; no MCP is used.

Scope

• In scope: detecting which of the three Fulfiller persona permsets (IncidentFulfiller, ProblemFulfillerPermSet, ChangeRequestFulfillerPermSet) are provisioned on the org, letting the user pick which persona to assign, checking existing assignments, assigning the permission-set license (when the persona is license-gated) and permission set to the running user (or a named user), verifying the target svc_itsm_intelligence__* invocable actions surface via a follow-up /actions/custom/generatePromptResponse read.
• Out of scope: Employee-agent access (different access model, different skill), installing/enabling the ITSM AddOn(s) or content bundle (hand off to service-itsm-agentic-setup-agentforce-studio-validate), enabling org-level Agentforce feature toggles, creating a permission set, creating or activating the Fulfiller agent (that's service-itsm-agentic-setup-fulfiller-agent-configure), CMDB access (service-itsm-agentic-setup-cmdb-access-assign), generic non-ITSM permission-set assignment (dx-org-permission-set-assign).

Mechanism

Two branches, decided by a read-only detection step first:

• Branch A — one or more Fulfiller persona permsets exist on the org. Ask the user which persona to assign (do not auto-select — a Fulfiller commonly needs only one). Idempotent assign: PSL first when the persona is license-gated, then permission set, verified by read-back and by a follow-up /actions/custom/generatePromptResponse read.
• Branch B — none of the three Fulfiller persona permsets exist on the org. The ITSM AddOn(s) are not provisioned; permset-assign is a no-op. STOP and hand off to service-itsm-agentic-setup-agentforce-studio-validate so the AddOn(s) can be enabled first.

The two-branch shape is deliberate — the failure signature ("svc_itsm_intelligence__X does not exist" on activate) looks identical whether a persona is present-and-unassigned or the AddOn is absent entirely, and there is no way to tell from the activate response alone. The pre-check on the three persona PermissionSet names is what disambiguates them.

Four helper scripts (all invoked via Bash) hold every deterministic decision (A9). Full I/O contracts in references/helper-contracts.md; workflow-level usage summarized below:

• scripts/classify-permset-availability.mjs — Branch A vs B and the per-persona needsPsl flag. Returns the full candidates[] (personas actually on the org) for the caller to prompt on.
• scripts/resolve-target-user.mjs — extracts 005… running-user Id from the API-root identity URL. Fails closed on any malformed shape.
• scripts/classify-assignment-state.mjs — idempotency; pass the sentinel NO-PSL in place of the PSLA path when the selected persona's needsPsl:false.
• scripts/classify-action-surface.mjs — Phase 4 verify verdict from the /actions/custom/generatePromptResponse capture (with optional expected-actions CSV).

Preconditions

1. sf CLI installed and authenticated to the target org (sf org display -o <alias> shows Connected). All calls use --target-org <alias>; never extract or pass the access token by hand.
2. API v67.0+.
3. node ≥ 18 on PATH.

If a precondition fails, sf surfaces an auth or 401/403/404; report the raw response verbatim and stop.

Clarifying questions

Ask only what cannot be inferred from conversation:

• Target org — the sf alias. Default to sf config get target-org if unset.
• Target user — default to the running user (resolved via scripts/resolve-target-user.mjs). If the user asks to assign on behalf of a named user, resolve them by Username first.
• Which Fulfiller persona? Incident / Problem / Change. Only ask about personas that are actually provisioned on the org (from candidates[]). Do not auto-select — a Fulfiller commonly needs only one persona (e.g. Incident) even when others are provisioned.
• Confirm the write — assigning a permission-set license consumes a seat and takes effect for a live user session. Present the target user + org + persona permset name, and require an explicit "yes" via AskUserQuestion before writing.

Workflow

All calls go through sf; substitute <alias> with the target org.

Phase 1 — Read: which Fulfiller persona permsets are provisioned on this org?

1. Query PermissionSet for the three known Fulfiller persona DeveloperNames:

   sf data query \
     -q "SELECT Id, Name, Label, LicenseId FROM PermissionSet WHERE Name IN ('IncidentFulfiller','ProblemFulfillerPermSet','ChangeRequestFulfillerPermSet')" \
     --target-org <alias> --json > /tmp/itsm-personas.json 2>/tmp/itsm-personas.err || true
   

   Copy

   (The PermissionSet namespace on all three is force — do NOT filter by NamespacePrefix.)

2. Classify:

   node "<skill_dir>/scripts/classify-permset-availability.mjs" /tmp/itsm-personas.json
   

   Copy

   The classifier prints { personasFound, personasMissing, candidates, verdict, reasons }, where each candidates[] row is {Id, Name, Label, LicenseId, needsPsl}:

   • verdict:"ASSIGN" (≥1 persona present) ⇒ continue to Phase 2. Present the personasFound list to the user via AskUserQuestion and get the selected persona; record its Id, LicenseId, and needsPsl — they drive whether Phase 2b/2d touch the PSL at all.
   • verdict:"HAND-OFF" (none of the three personas present) ⇒ Phase 2 is impossible on this org; go to Phase 3 (Branch B hand-off).
   • verdict:"CANNOT-CONFIRM" (query failed) ⇒ surface the raw CLI error verbatim; stop.

Phase 2 — Assign path (Branch A)

2a. Resolve the target user. Read the identity URL, then extract the user Id via the resolver (do NOT parse the URL by hand; do NOT use USER_ID() — Apex-only, rejected by REST; do NOT rely on /chatter/users/me — 403 when Chatter is off):

sf api request rest "/services/data/v67.0/" --method GET --target-org <alias> > /tmp/api-root.json 2>/tmp/api-root.err || true
node "<skill_dir>/scripts/resolve-target-user.mjs" /tmp/api-root.json

The resolver prints { userId, identity, verdict, reasons }. On verdict:"RESOLVED" use userId as the running user; on verdict:"CANNOT-CONFIRM" surface the reasons verbatim and stop — do NOT guess.

If the user asks to assign on behalf of a named user instead, resolve by Username:

sf data query \
  -q "SELECT Id, Username, Name, IsActive FROM User WHERE Username = '<username>'" \
  --target-org <alias> --json > /tmp/user-lookup.json 2>/tmp/user-lookup.err || true

2b. Idempotency read. Query the PermissionSetAssignment for the target user + selected persona's Id (SOQL shape in references/cli-invocation.md), and then branch on the selected persona's needsPsl:

• needsPsl:true — query the PermissionSetLicenseAssign for the target user + the persona's LicenseId, then classify:

  node "<skill_dir>/scripts/classify-assignment-state.mjs" /tmp/psa-existing.json /tmp/psla-existing.json
  

  Copy

• needsPsl:false — skip the PSLA query entirely; pass the sentinel:

  node "<skill_dir>/scripts/classify-assignment-state.mjs" /tmp/psa-existing.json NO-PSL
  

  Copy

The classifier prints { permsetAssigned, licenseAssigned, needsWrite, verdict, reasons }. If needsWrite:false ⇒ Phase 4 (verify only). Else continue to Phase 2c.

2c. Confirm-to-write checkpoint (REQUIRED). Present the target user + org + persona permset name and require an explicit "yes" via AskUserQuestion. On "no", stop and report the current state without any writes.

2d. Assign — order depends on the selected persona's needsPsl:

• needsPsl:true — POST the PSL to /sobjects/PermissionSetLicenseAssign FIRST, then run sf org assign permset --name <permsetName> --on-behalf-of <userId>. Assigning the permission set without the PSL sticks the assignment but the license backing it never activates. Exact call shapes: references/cli-invocation.md.
• needsPsl:false — SKIP the PSL POST entirely; run sf org assign permset only. (A persona whose PermissionSet has no backing LicenseId is not license-gated — there is no PSL seat to hold, so assigning the permset alone is the correct and complete write.) Retained defensively: every shipped persona is now PSL-backed (needsPsl is derived per-row from LicenseId), so this false branch and its NO-PSL wiring are currently unexercised by shipped data — kept for correctness against a future persona whose PermissionSet carries no backing LicenseId.

Response handling:

• 201 on POST / success:true on sf org assign permset ⇒ assigned.
• 400 DUPLICATE_VALUE on the PSL POST ⇒ user already had it; treat as success, not error.
• 400 INSUFFICIENT_ACCESS / seat-exhaustion on the PSL POST ⇒ STOP for this write; tell the user the PSL has no seats available.

Phase 3 — Hand-off path (Branch B: no Fulfiller persona provisioned)

3. When Phase 1 returns verdict:"HAND-OFF", none of the three Fulfiller persona permsets exist on this org — the ITSM AddOn(s) are not provisioned. Permset-assign is a no-op in this state. Present the discovery via AskUserQuestion:

   "None of the Fulfiller persona permission sets (Incident, Problem, Change) is provisioned on this org — no permset can grant access to actions that don't exist yet. Run service-itsm-agentic-setup-agentforce-studio-validate to diagnose which AddOn needs enabling?" (options: Yes, run the readiness check / No, stop here).

   • On Yes: delegate to service-itsm-agentic-setup-agentforce-studio-validate and let it recommend the configure/bundle-deploy skill.
   • On No: stop and report the current state (no persona provisioned, cannot assign) — no writes.

Phase 4 — Verify

4. Regardless of write vs skip, re-read /actions/custom/generatePromptResponse and classify via the helper (never by prose grep — A9). CSV shape and both invocation forms live in references/helper-contracts.md / references/cli-invocation.md:

   sf api request rest "/services/data/v67.0/actions/custom/generatePromptResponse" \
     --method GET --target-org <alias> > /tmp/generate-prompt-response.json 2>/tmp/generate-prompt-response.err || true
   node "<skill_dir>/scripts/classify-action-surface.mjs" /tmp/generate-prompt-response.json [expectedActions-csv]
   

   Copy

   The helper prints { present, missing, totalItsmActionsSeen, verdict, reasons }. On SURFACED proceed to Phase 5; on PARTIAL / MISSING after a successful assign, tell the user the write succeeded but the actions are not surfaced — session refresh or wrong persona. Do not falsely report success. On CANNOT-CONFIRM surface the reasons verbatim.

Phase 5 — Aggregate verdict

5. Report one of:
   • ASSIGNED — Branch A wrote, verify saw the target actions surface.
   • ALREADY-ASSIGNED — Branch A found needsWrite:false; verify saw the target actions surface. (Assignment is already in place; no writes needed.)
   • HAND-OFF — Branch B; no Fulfiller persona is provisioned. Named the follow-up skill.
   • VERIFY-INCONCLUSIVE — write completed but the verify read didn't surface the expected action set. Surface the observed state verbatim; do not report success.
   • FAILED — any Phase 2d write returned an error other than DUPLICATE_VALUE. Report the raw error.

Rules / Constraints

Verification Checklist

• Persona availability classified by scripts/classify-permset-availability.mjs against the three fixed persona Names — never by prose scanning the query output.
• User was asked to pick a persona from personasFound[] — no auto-selection.
• Target user Id resolved by scripts/resolve-target-user.mjs — never by prose splitting the identity URL.
• The SELECTED persona's needsPsl drove Phase 2b/2d: PSL SOQL + POST were performed when true and skipped when false.
• permsetLicenseId used for the PSL POST came from the SELECTED persona's own LicenseId — never a fallback from a namespace-wide query.
• On Branch A: existing assignments read via sf data query before any write, classified by scripts/classify-assignment-state.mjs (with NO-PSL sentinel when needsPsl:false).
• On Branch A: user confirmed the write at the Phase 2c checkpoint.
• On Branch A + needsPsl:true: PSL was POSTed before the permission set was assigned.
• DUPLICATE_VALUE on the PSL POST was treated as success, not failure.
• On Branch B: no write was attempted; the hand-off to service-itsm-agentic-setup-agentforce-studio-validate was offered.
• Phase 4 verify classified via scripts/classify-action-surface.mjs — no false ASSIGNED without the helper returning verdict:"SURFACED".
• Aggregate verdict reported (ASSIGNED / ALREADY-ASSIGNED / HAND-OFF / VERIFY-INCONCLUSIVE / FAILED).

Output Format

ITSM Fulfiller Persona Permset Assignment (via service-itsm-agentic-setup-itsm-agentforce-permset-assign)

Org:            <org-alias> (API v67.0)
Target user:    <username> (<userId>)
Persona:        <Incident | Problem | Change>
PermSet:        <DeveloperName>

  Personas provisioned on org ...... <comma-separated list | none>
  Existing PSL assignment .......... <yes | no | n/a>
  Existing permset assignment ...... <yes | no>
  Write PSL ........................ <succeeded | already-had | skipped | FAILED>
  Write permset .................... <succeeded | already-had | skipped | FAILED>
  Verify actions surface ........... <yes | partial | no>

Verdict: ASSIGNED | ALREADY-ASSIGNED | HAND-OFF | VERIFY-INCONCLUSIVE | FAILED
Reason:  <plain-language explanation, or empty on success>

Next steps:
  - <If ASSIGNED / ALREADY-ASSIGNED: "Re-run service-itsm-agentic-setup-fulfiller-agent-configure — the invocable actions should now surface, and the activate call will succeed.">
  - <If HAND-OFF: "No Fulfiller persona is provisioned on this org. Run service-itsm-agentic-setup-agentforce-studio-validate to identify which AddOn needs enabling.">
  - <If VERIFY-INCONCLUSIVE: list the observed state verbatim; a session refresh or a different persona may be required>
  - <If FAILED: list the observed error verbatim + remediation>

Keep internal jargon (record Ids, HTTP status codes, FUNCTIONALITY_NOT_ENABLED, DUPLICATE_VALUE, object/developer names, sf api request rest) out of user-facing output.

Reference File Index