Skip to content

Commit b5d07fd

Browse files
claveryclavery
authored
Add BM instance-level role management commands (#293)
* 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. * Add SDK migration tutorial for sfcc-ci programmatic API users New guide at docs/guide/sdk-migration.md covering the migration from sfcc-ci's require('sfcc-ci') JavaScript API to @salesforce/b2c-tooling-sdk. Includes side-by-side code examples, paradigm shift explanations (callbacks→async/await, token passing→config-based auth, untyped→typed), per-module API mapping, and a comprehensive reference table. Also adds cross-references from the CLI migration guide and SDK README. * Move description to extended column in bm roles list Long descriptions overflow the terminal width. Match the pattern used by scaffold list/search where description is an extended-only column.
1 parent f56be93 commit b5d07fd

26 files changed

Lines changed: 2445 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

‎.changeset/sdk-migration-tutorial.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@salesforce/b2c-dx-docs': patch
3+
---
4+
5+
Add SDK migration tutorial for sfcc-ci programmatic API users

‎docs/.vitepress/config.mts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ const guidesSidebar = [
4444
{text: 'Authentication Setup', link: '/guide/authentication'},
4545
{text: 'CI/CD with GitHub Actions', link: '/guide/ci-cd'},
4646
{text: 'sfcc-ci Migration', link: '/guide/sfcc-ci-migration'},
47+
{text: 'sfcc-ci SDK Migration', link: '/guide/sdk-migration'},
4748
{text: 'Account Manager', link: '/guide/account-manager'},
4849
{text: 'Analytics Reports (CIP/CCAC)', link: '/guide/analytics-reports-cip-ccac'},
4950
{text: 'IDE Integration', link: '/guide/ide-integration'},
@@ -79,6 +80,7 @@ const referenceSidebar = [
7980
{text: 'Overview', link: '/cli/'},
8081
{text: 'Account Manager', link: '/cli/account-manager'},
8182
{text: 'Auth', link: '/cli/auth'},
83+
{text: 'BM Roles', link: '/cli/bm-roles'},
8284
{text: 'CIP', link: '/cli/cip'},
8385
{text: 'Code', link: '/cli/code'},
8486
{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+
```

0 commit comments

Comments
 (0)