service-omni-queue-members-assign — Claude Code skill
service-omni-queue-members-assign — a Claude Code skill that assigns agent users to Salesforce queues via the Data API. Populates Case and Voice queues so Omni-Channel routing can distribute work items.
Apache-2.0 106 installs ★ 1,183 updated 2026-10-23
npx skills add forcedotcom/sf-skills --skill service-omni-queue-members-assign -a claude-codeWhat service-omni-queue-members-assign does
The skill links users to a target Salesforce queue by issuing individual POST requests to the GroupMember object. The verify-and-bind.sh script executes a SOQL query first to detect existing memberships and writes only missing records. It handles either generated demo accounts like agent{1..N} or an explicit CSV list of usernames and 15/18-character User IDs.
Existing memberships remain untouched because the script never deletes or reassigns records. It also cannot create queues or users, which must exist beforehand. The safe_to_write guard blocks runs on production orgs without an override option to prevent routing real customer traffic to test accounts.
Prerequisites include a Service Cloud license, PermissionsModifyAllData, sf CLI 2.139.6 or later, python3 3.8+, and jq 1.6+. Output is structured as a JSON document reporting status values such as bound, reused, partial, or blocked.
What it helps with
- assign generated demo agents to CaseQueue in a scratch org
- bind specific agents to a Voice queue using usernames or User IDs
- populate Salesforce queue members before Omni-Channel routing tests
- detect missing queue memberships idempotently before posting
Example prompts for the agent
- Assign 3 demo agents to CaseQueue in myorg
- Add [email protected] and 005XX000001abcd to VoiceQueue
- Check membership for CaseQueue and bind missing operators
How to install service-omni-queue-members-assign
1Skills CLI (Vercel)
npx skills add forcedotcom/sf-skills --skill service-omni-queue-members-assign -a claude-code2Manually: put the files in place
~/.claude/skills/service-omni-queue-members-assign/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/service-omni-queue-members-assign/
1Skills CLI (Vercel)
npx skills add forcedotcom/sf-skills --skill service-omni-queue-members-assign -a codex2Manually: put the files in place
.agents/skills/service-omni-queue-members-assign/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add forcedotcom/sf-skills --skill service-omni-queue-members-assign -a cursor2Manually: put the files in place
.cursor/skills/service-omni-queue-members-assign/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install forcedotcom/sf-skills skills/service-omni-queue-members-assign2Manually: put the files in place
.github/skills/service-omni-queue-members-assign/SKILL.md1Skills CLI (Vercel)
npx skills add forcedotcom/sf-skills --skill service-omni-queue-members-assign -a gemini-cli2Platform CLI
gemini skills install https://github.com/forcedotcom/sf-skills --path skills/service-omni-queue-members-assignManually: put the files in place
.devin/skills/service-omni-queue-members-assign/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add forcedotcom/sf-skills --skill service-omni-queue-members-assign -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about service-omni-queue-members-assign
How to install service-omni-queue-members-assign in Claude Code?
Run npx skills add forcedotcom/sf-skills --skill service-omni-queue-members-assign -a claude-code.
What does service-omni-queue-members-assign do?
It creates GroupMember records via the Salesforce Data API so Omni-Channel routing finds active members in a queue.
What is required to run service-omni-queue-members-assign?
It requires sf CLI >= 2.139.6, jq >= 1.6, python3 >= 3.8, a Service Cloud license, and PermissionsModifyAllData on a non-production org.
Source text
SKILL.md · Apache-2.0
---
name: service-omni-queue-members-assign
description: "Use to bind agent users into a Salesforce Queue via GroupMember Data API POSTs, with SOQL-based idempotency (safe re-run — only inserts missing bindings). Binds either the generated demo agents (agent{1..N}.<suffix>@example.com) or an explicit list of real agents passed as usernames/User Ids. Triggers: add agents to a Case/Voice queue, assign agent users to a queue, populate queue membership for Omni routing. Do not use to create the queue (service-omni-queue-deploy), to create the agent users (service-omni-agent-users-create), or to assign permission sets (service-omni-permission-set-assign)."
allowed-tools: Bash Read Write Edit Glob Grep
metadata:
version: "1.0"
domains: ["Service"]
minApiVersion: "66.0"
relatedSkills:
- "service-omni-agent-users-create"
- "service-omni-permission-set-assign"
- "service-omni-queue-deploy"
- "service-omni-queue-routing-config-deploy"
accessCheck: "OrgPermissions.LightningService"
cliTools:
- tool: ["jq"]
semver: ">=1.6"
- tool: ["python3"]
semver: ">=3.8"
- tool: ["sf"]
semver: ">=2.139.6"
---
# service-omni-queue-members-assign
Bind N agent users into a Salesforce Queue via `GroupMember` Data API POSTs. Without queue membership, Omni-Channel routing sees an empty pool for the queue and never assigns work. Detection is SOQL-based (the same detect-then-POST shape as `service-omni-queue-routing-config-deploy`), so only missing memberships are created and the skill is safe to re-run. Agent users come from `service-omni-agent-users-create`, the queue from `service-omni-queue-deploy`, and the users' Omni permissions from `service-omni-permission-set-assign`.
## Inputs
```bash
bash scripts/verify-and-bind.sh <org-alias> [queue-developer-name=CaseQueue] [count=3] [explicit-members-csv]
# demo agents (default):
bash scripts/verify-and-bind.sh myorg CaseQueue 3
# real agents by username/id:
bash scripts/verify-and-bind.sh myorg VoiceQueue "" "[email protected],005XX000001abcd"
```
- `org-alias` (required).
- `queue-developer-name` (optional, default `CaseQueue`).
- `count` (optional, default `3`, range `1..10`) — must match the agent user count; ignored in explicit mode.
- `explicit-members-csv` (optional 4th positional, or `MEMBER_USERNAMES_CSV` / `MEMBER_USER_IDS_CSV`) — each token is a Username or a 15/18-char User Id; the count is derived from the list.
## Preconditions and safety
- Target org authenticated via `sf` CLI (My Domain URL), Service Cloud license, `sf` CLI ≥ 2.139.6.
- The executing user has `PermissionsModifyAllData` (standard on System Administrator).
- The agent users exist (`service-omni-agent-users-create`) and the queue exists (`service-omni-queue-deploy`); a missing user set or queue blocks with a pointer to the right skill (queues cannot be created via the Data API).
- The three-way `safe_to_write` production guard applies — adding users to a production queue mis-routes real customer work, so it blocks with no override.
## Run
`verify-and-bind.sh` runs the whole cycle:
1. Compute `safe_to_write`; derive the 8-char org suffix.
2. Resolve the queue `Group.Id` by DeveloperName + `Type='Queue'`; block if missing.
3. Resolve the member set — generated mode queries `User` for `agent{1..N}.<suffix>@example.com` (block if any expected user is missing); explicit mode resolves each supplied token and requires every one to be an ACTIVE user.
4. Query existing `GroupMember` for the queue; compute the users not yet bound.
5. POST one `GroupMember` per missing user (individual POSTs, no `allOrNone`).
6. Re-query to confirm final membership and emit the report.
## Behavior
**Two member sources, never mixed.** The default generated pattern keeps the user-create → member-assign handoff deterministic; explicit mode is opt-in for real agents and takes over count derivation. In explicit mode, a token that does not resolve to an active user blocks the run — binding a typo'd or inactive user would silently under-populate the queue.
**Idempotency and honesty.** POSTs are individual so one failed binding (e.g. a race with another admin) never rolls back its successful siblings, and the skill re-queries after all POSTs — a 201 only means the write was accepted; a subsequent SOQL confirms the row is visible to the routing engine. The `before` snapshot includes members already present, even non-demo users added out-of-band, so the coordinator can see full membership state.
**Non-destructive.** Create-only; it never removes or reassigns existing members.
## Output contract
A single JSON object with `status` ∈ `bound` | `reused` | `partial` | `blocked`, the resolved `queue`, `org_suffix`, `member_source` (`generated_pattern` | `explicit`), `requested_count`, a `before` snapshot, `bound_this_run`/`bound_count`, `reused_count`, an `after` snapshot, `manual_actions`, and `blocking_issue`.
- `bound` — at least one new member created; final state matches the expected count.
- `reused` — all expected users were already members; nothing POSTed.
- `partial` — some POSTs failed; the re-query shows fewer members than requested (details in `blocking_issue`).
- `blocked` — precondition failed (production org, missing queue, missing users, missing permissions).
`bound_count + reused_count == requested_count` unless `partial`; `blocking_issue` is non-null only for `blocked`/`partial`.
## Limitations
- Generated and explicit modes are mutually exclusive per run.
- Create-only; removing or reassigning members is out of scope.
- Does not create the queue or the users, and does not assign permission sets or presence configs.
## References
| File | When to read |
|---|---|
| `references/api-notes.md` | Before the detect/bind cycle — GroupMember schema, the queue-vs-public-group distinction, why `UserOrGroupId` is polymorphic, and common POST failures |
| `scripts/tests/test_queue_members_contracts.py` | When validating changes — run `python3 scripts/tests/test_queue_members_contracts.py` from this skill directory |
© forcedotcom · Apache-2.0 · forcedotcom/sf-skills