forcedotcom/sf-skills / plugins/builder/service-itsm/skills/service-itsm-agentic-setup-employee-agent-configure
service-itsm-agentic-setup-employee-agent-configure
UnverifiedCreate and activate an IT Service Employee agent as a Next-Gen Authoring (NGA) native agent from an ITSM Employee agent template's Agent Script, via the Salesforce CLI (sf): read the template, check idempotency, create the NGA bundle then publish and activate, verify live. Defaults to the broad IT Service Employee template; when the user names a specialized Employee template (Password Manager Assistance, Certificate Management, Onboarding, Hardware Request, and ~47 others catalogued in references/specialized-templates.md — all under the `svc_emp_intelligence__` namespace), pins that one instead. Idempotent per developer name. TRIGGER when the user asks to create/set up/provision/activate the Employee agent, the IT Service Employee agent, or a specialized Employee agent (password manager, certificate, onboarding, hardware request, etc.). DO NOT TRIGGER: prerequisite checks (service-itsm-agentic-setup-agentforce-studio-validate), CMDB CRUD, Fulfiller setup (service-itsm-agentic-setup-fulfiller-agent-configure).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 29.4 KB |
| references/cli-invocation.md | markdown | 22.4 KB |
| references/error-taxonomy.md | markdown | 4.1 KB |
| references/reactivation.md | markdown | 4.2 KB |
| references/report-format.md | markdown | 4.9 KB |
| references/specialized-templates.md | markdown | 10.5 KB |
| references/workflow-detail.md | markdown | 18.2 KB |
| scripts/build-create-body.mjsexecutable | script | 4.7 KB |
| scripts/classify-agent-existence.mjsexecutable | script | 13.5 KB |
| scripts/classify-preflight.mjsexecutable | script | 11.4 KB |
| scripts/create-scratch-dir.mjsexecutable | script | 2.3 KB |
| scripts/render-report.mjsexecutable | script | 12.2 KB |
references/reactivation.md
View on GitHub# Reactivation path — activating an existing inactive IT Service Employee Agent
Split from `references/cli-invocation.md` — this file documents the direct
`BotVersion` activation call used when the Phase-2 classifier reports the agent
already exists but its latest version is `Inactive`. `cli-invocation.md` covers
the create/publish/activate happy path; this file covers "skip create/publish,
just reactivate what's already there".
## When this path fires
`scripts/classify-agent-existence.mjs` (called with the template's
`botDefinitionId` as the PRIMARY idempotency key, the BotDefinition's
`AgentTemplate` — the template's OOTB source id — as the first FALLBACK, and the
collected `DeveloperName` as the last FALLBACK —
see `cli-invocation.md` → "Enumerate the existing agent") returns
`{ exists:true, needsActivation:true, latestVersionId, latestVersionStatus:"Inactive" }`.
That means a `BotDefinition` matching the template (by `botDefinitionId`), its
`AgentTemplate` source id, or the collected `DeveloperName` already exists (created
on a prior run, or — for the broad Employee agent, matched by its source template —
by the platform) but its most-recent `BotVersion` is
inactive; creating a new bundle would produce a duplicate. Instead, flip the
existing version to `Active`.
## Activate an existing inactive version — `POST /connect/bot-versions/{id}/activation`
```bash
sf api request rest "/services/data/v67.0/connect/bot-versions/<latestVersionId>/activation" \
--method POST --body '{"status":"Active"}' \
--target-org <alias> > ${SCRATCH_DIR}/activate-existing.json 2>${SCRATCH_DIR}/activate-existing.err || true
```
`<latestVersionId>` is the captured `latestVersionId` from the Phase-2
classifier output — **not** a bundle version id. This is a direct
`BotVersion` activation toggle that bypasses the NGA bundle pipeline entirely,
because the `BotDefinition`/`BotVersion` records already exist. Skips create
(Phase 4) and publish (Phase 5) — go straight to activate, then verify.
## Verify — same SOQL as the happy path
Run the Phase-7 verify read (see `cli-invocation.md` → "Verify the agent is
live"). Confirm `exists:true` with `count:1` **and**
`latestVersionStatus:"Active"`. If `latestVersionStatus` is still `Inactive`
after a successful activation call, report the discrepancy verbatim — do not
fabricate success.
## Idempotency semantics
| Signal | Verdict |
|--------|---------|
| Neither the template's `botDefinitionId` nor the collected `DeveloperName` matches a live `BotDefinition` — classifier returns `exists:false` | proceed to CREATE |
| Phase-2 classifier returns `exists:true` and `needsActivation:false` (latest version `Active`), matched by `botDefinitionId` or the `DeveloperName` fallback | ALREADY-CREATED (skip create/publish/activate entirely) |
| Phase-2 classifier returns `exists:true` and `needsActivation:true` (latest version `Inactive`), user confirms reactivation, and the bot-version activation call succeeds | ACTIVATED (skip create/publish entirely — direct `BotVersion` activation only) |
| `createBundleWithVersion` → `publish` → `activate` all succeed and Phase-7 classifier (keyed on the publish `publishedBotId`) confirms `exists:true` with `latestVersionStatus:"Active"` | CREATED |
The server-side create path **does** reject a duplicate, but keyed on
`DeveloperName`, not `apiName`: a pre-validation lookup
(`lookupBotDefinitionIdByDeveloperName`) plus a publish-time `BotDefinition`
DeveloperName unique-constraint catch that cleans up the orphaned bundle version.
That guard fires only when the `DeveloperName` being created already exists — so
it catches a repeat run of THIS skill (same collected `developerName`), but it
does **not** catch the pre-provisioned broad Employee agent, whose live
`DeveloperName` (`IT_Service_Employee`) differs from this skill's guess
(`IT_Service_Employee_Agent`). The Phase-2 read closes that gap and upgrades the
outcome from a hard error to a graceful skip: it keys on the template's
`botDefinitionId` (primary — catches the pre-provisioned agent regardless of
name) and falls back to the collected `DeveloperName` (catches a self-created
repeat), so both surface as ALREADY-CREATED / reactivation instead of a
`DUPLICATE_VALUE` from the create call.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |