Skip to content

Commit bc326ee

Browse files
claveryclavery
committed
Add Business Manager instance-level role management commands
Close the sfcc-ci compatibility gap for role operations that target a specific instance (the `--instance` flag in sfcc-ci). Adds a new `bm roles` topic with full CRUD, user assignment, and permissions management via OCAPI Data API, mirroring the existing `am roles` topic structure. New SDK operations: listBmRoles, getBmRole, createBmRole, deleteBmRole, grantBmRole, revokeBmRole, getBmRolePermissions, setBmRolePermissions. New CLI commands: bm roles list/get/create/delete/grant/revoke and bm roles permissions get/set. Also updates the sfcc-ci migration guide, adds documentation, and creates a b2c-users-roles skill covering both AM and BM role management.
1 parent f56be93 commit bc326ee

23 files changed

Lines changed: 1955 additions & 11 deletions

File tree

‎.changeset/bm-roles-management.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
'@salesforce/b2c-cli': minor
3+
'@salesforce/b2c-tooling-sdk': minor
4+
'@salesforce/b2c-dx-docs': patch
5+
---
6+
7+
Add Business Manager role management commands (`bm roles`) for instance-level access role CRUD, user assignment, and permissions via OCAPI Data API

‎docs/.vitepress/config.mts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,7 @@ const referenceSidebar = [
7979
{text: 'Overview', link: '/cli/'},
8080
{text: 'Account Manager', link: '/cli/account-manager'},
8181
{text: 'Auth', link: '/cli/auth'},
82+
{text: 'BM Roles', link: '/cli/bm-roles'},
8283
{text: 'CIP', link: '/cli/cip'},
8384
{text: 'Code', link: '/cli/code'},
8485
{text: 'Content', link: '/cli/content'},

‎docs/cli/bm-roles.md‎

Lines changed: 309 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,309 @@
1+
---
2+
description: Commands for managing Business Manager access roles, user assignments, and permissions on B2C Commerce instances.
3+
---
4+
5+
# BM Roles Commands
6+
7+
Commands for managing instance-level Business Manager access roles on B2C Commerce instances. These are distinct from [Account Manager roles](/cli/account-manager#roles) which manage roles at the Account Manager level.
8+
9+
## Authentication
10+
11+
BM roles commands require OAuth authentication with OCAPI permissions for the `/roles` resource.
12+
13+
### Required OCAPI Permissions
14+
15+
| Resource | Methods |
16+
|----------|---------|
17+
| `/roles` | GET |
18+
| `/roles/*` | GET, PUT, DELETE |
19+
| `/roles/*/users` | GET, PUT, DELETE |
20+
21+
### Configuration
22+
23+
```bash
24+
export SFCC_CLIENT_ID=your-client-id
25+
export SFCC_CLIENT_SECRET=your-client-secret
26+
```
27+
28+
For complete setup instructions, see the [Authentication Guide](/guide/authentication).
29+
30+
---
31+
32+
## b2c bm roles list
33+
34+
List all Business Manager access roles on an instance.
35+
36+
### Usage
37+
38+
```bash
39+
b2c bm roles list [--count <n>] [--start <n>]
40+
```
41+
42+
### Flags
43+
44+
| Flag | Description |
45+
|------|-------------|
46+
| `--count`, `-n` | Number of roles to return (default 25) |
47+
| `--start` | Start index for pagination (default 0) |
48+
49+
Uses [global instance and authentication flags](./index#global-flags).
50+
51+
### Examples
52+
53+
```bash
54+
b2c bm roles list --server my-sandbox.demandware.net
55+
b2c bm roles list --count 50 --json
56+
```
57+
58+
---
59+
60+
## b2c bm roles get
61+
62+
Get details of a specific access role.
63+
64+
### Usage
65+
66+
```bash
67+
b2c bm roles get <role> [--expand <expansion>]
68+
```
69+
70+
### Arguments
71+
72+
| Argument | Description |
73+
|----------|-------------|
74+
| `role` | Role ID (e.g. "Administrator") |
75+
76+
### Flags
77+
78+
| Flag | Description |
79+
|------|-------------|
80+
| `--expand`, `-e` | Expansions to apply (e.g. `users`, `permissions`). Can be specified multiple times. |
81+
82+
### Examples
83+
84+
```bash
85+
b2c bm roles get Administrator
86+
b2c bm roles get Administrator --expand users
87+
b2c bm roles get Administrator --json
88+
```
89+
90+
---
91+
92+
## b2c bm roles create
93+
94+
Create a new custom access role on an instance.
95+
96+
### Usage
97+
98+
```bash
99+
b2c bm roles create <role> [--description <text>]
100+
```
101+
102+
### Arguments
103+
104+
| Argument | Description |
105+
|----------|-------------|
106+
| `role` | Role ID to create |
107+
108+
### Flags
109+
110+
| Flag | Description |
111+
|------|-------------|
112+
| `--description`, `-d` | Description for the role |
113+
114+
### Examples
115+
116+
```bash
117+
b2c bm roles create ContentEditor --description "Role for content editors"
118+
b2c bm roles create ContentEditor --json
119+
```
120+
121+
::: warning
122+
Reserved role IDs ("Support", "Business Support") cannot be created.
123+
:::
124+
125+
---
126+
127+
## b2c bm roles delete
128+
129+
Delete a custom access role from an instance.
130+
131+
### Usage
132+
133+
```bash
134+
b2c bm roles delete <role>
135+
```
136+
137+
### Arguments
138+
139+
| Argument | Description |
140+
|----------|-------------|
141+
| `role` | Role ID to delete |
142+
143+
### Examples
144+
145+
```bash
146+
b2c bm roles delete ContentEditor
147+
```
148+
149+
::: warning
150+
System roles (e.g. "Administrator") cannot be deleted.
151+
:::
152+
153+
---
154+
155+
## b2c bm roles grant
156+
157+
Assign a user to an access role on an instance.
158+
159+
### Usage
160+
161+
```bash
162+
b2c bm roles grant <login> --role <role>
163+
```
164+
165+
### Arguments
166+
167+
| Argument | Description |
168+
|----------|-------------|
169+
| `login` | User login (email) |
170+
171+
### Flags
172+
173+
| Flag | Description |
174+
|------|-------------|
175+
| `--role`, `-r` | Role ID to grant (required) |
176+
177+
### Examples
178+
179+
```bash
180+
b2c bm roles grant user@example.com --role Administrator
181+
b2c bm roles grant user@example.com --role ContentEditor --json
182+
```
183+
184+
---
185+
186+
## b2c bm roles revoke
187+
188+
Unassign a user from an access role on an instance.
189+
190+
### Usage
191+
192+
```bash
193+
b2c bm roles revoke <login> --role <role>
194+
```
195+
196+
### Arguments
197+
198+
| Argument | Description |
199+
|----------|-------------|
200+
| `login` | User login (email) |
201+
202+
### Flags
203+
204+
| Flag | Description |
205+
|------|-------------|
206+
| `--role`, `-r` | Role ID to revoke (required) |
207+
208+
### Examples
209+
210+
```bash
211+
b2c bm roles revoke user@example.com --role Administrator
212+
```
213+
214+
---
215+
216+
## b2c bm roles permissions get
217+
218+
Get permissions for an access role.
219+
220+
### Usage
221+
222+
```bash
223+
b2c bm roles permissions get <role> [--output <file>]
224+
```
225+
226+
### Arguments
227+
228+
| Argument | Description |
229+
|----------|-------------|
230+
| `role` | Role ID (e.g. "Administrator") |
231+
232+
### Flags
233+
234+
| Flag | Description |
235+
|------|-------------|
236+
| `--output`, `-o` | Write full permissions JSON to a file for editing |
237+
238+
### Examples
239+
240+
```bash
241+
# View summary
242+
b2c bm roles permissions get Administrator
243+
244+
# Export to file for editing
245+
b2c bm roles permissions get Administrator --output admin-perms.json
246+
247+
# Get raw JSON
248+
b2c bm roles permissions get Administrator --json
249+
```
250+
251+
---
252+
253+
## b2c bm roles permissions set
254+
255+
Set (replace) all permissions for an access role from a JSON file.
256+
257+
### Usage
258+
259+
```bash
260+
b2c bm roles permissions set <role> --file <path>
261+
```
262+
263+
### Arguments
264+
265+
| Argument | Description |
266+
|----------|-------------|
267+
| `role` | Role ID |
268+
269+
### Flags
270+
271+
| Flag | Description |
272+
|------|-------------|
273+
| `--file`, `-f` | JSON file containing permissions (`role_permissions` schema) (required) |
274+
275+
### Examples
276+
277+
```bash
278+
# Export, edit, then apply
279+
b2c bm roles permissions get MyRole --output perms.json
280+
# ... edit perms.json ...
281+
b2c bm roles permissions set MyRole --file perms.json
282+
```
283+
284+
::: warning
285+
This command replaces **all** existing permissions for the role. Use `permissions get --output` first to ensure you have the complete set.
286+
:::
287+
288+
### Permissions JSON Structure
289+
290+
The JSON file follows the OCAPI `role_permissions` schema with four sections:
291+
292+
```json
293+
{
294+
"functional": {
295+
"organization": [{"name": "PERMISSION_NAME", "type": "functional", "value": "ACCESS"}],
296+
"site": []
297+
},
298+
"module": {
299+
"organization": [{"application": "bm", "name": "ModuleName", "type": "module", "system": true, "value": "ACCESS"}],
300+
"site": []
301+
},
302+
"locale": {
303+
"unscoped": [{"locale_id": "default", "type": "locale", "value": "ACCESS"}]
304+
},
305+
"webdav": {
306+
"unscoped": [{"folder": "Catalogs", "type": "webdav", "value": "ACCESS"}]
307+
}
308+
}
309+
```

‎docs/guide/sfcc-ci-migration.md‎

Lines changed: 14 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -106,19 +106,22 @@ Sandbox commands map directly, with spaces replacing colons:
106106
| `sfcc-ci slas:client:list` | `b2c slas client list` |
107107
| `sfcc-ci slas:client:delete` | `b2c slas client delete` |
108108

109-
### User / Org / Role (Account Manager)
109+
### User / Org / Role
110110

111-
Account Manager operations are under the `am` topic:
111+
Account Manager operations are under the `am` topic. Instance-level Business Manager role management is under the `bm` topic:
112112

113-
| sfcc-ci | b2c-cli |
114-
|---------|---------|
115-
| `sfcc-ci user:list` | `b2c am users list` |
116-
| `sfcc-ci user:create` | `b2c am users create` |
117-
| `sfcc-ci user:delete` | `b2c am users delete` |
118-
| `sfcc-ci org:list` | `b2c am orgs list` |
119-
| `sfcc-ci role:list` | `b2c am roles list` |
120-
| `sfcc-ci role:grant` | `b2c am roles grant` |
121-
| `sfcc-ci role:revoke` | `b2c am roles revoke` |
113+
| sfcc-ci | b2c-cli | Notes |
114+
|---------|---------|-------|
115+
| `sfcc-ci user:list` | `b2c am users list` | |
116+
| `sfcc-ci user:create` | `b2c am users create` | |
117+
| `sfcc-ci user:delete` | `b2c am users delete` | |
118+
| `sfcc-ci org:list` | `b2c am orgs list` | |
119+
| `sfcc-ci role:list` | `b2c am roles list` | Account Manager roles |
120+
| `sfcc-ci role:list -i <instance>` | `b2c bm roles list` | Instance BM roles |
121+
| `sfcc-ci role:grant` | `b2c am roles grant` | Account Manager roles |
122+
| `sfcc-ci role:grant -i <instance>` | `b2c bm roles grant` | Instance BM roles |
123+
| `sfcc-ci role:revoke` | `b2c am roles revoke` | Account Manager roles |
124+
| `sfcc-ci role:revoke -i <instance>` | `b2c bm roles revoke` | Instance BM roles |
122125

123126
## Environment Variables
124127

‎packages/b2c-cli/package.json‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,19 @@
9898
},
9999
"topicSeparator": " ",
100100
"topics": {
101+
"bm": {
102+
"description": "Manage Business Manager resources on an instance",
103+
"subtopics": {
104+
"roles": {
105+
"description": "Manage instance-level Business Manager access roles",
106+
"subtopics": {
107+
"permissions": {
108+
"description": "Get and set permissions for Business Manager roles"
109+
}
110+
}
111+
}
112+
}
113+
},
101114
"auth": {
102115
"description": "Manage authentication credentials and tokens\n\nDocs: https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/auth.html"
103116
},

0 commit comments

Comments
 (0)