Skip to content

Commit 5816fc3

Browse files
claveryclavery
authored
Job execution commands and site archive import/export (#7)
* jobs wip * better argument parsing * more greedy prevention * job cleanup * cleanup * table cleanup * update docs * docs * description * topic fixes * better zip implementation
1 parent e1ed9f4 commit 5816fc3

25 files changed

Lines changed: 2514 additions & 478 deletions

File tree

‎docs/cli/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ These flags are available on all commands that interact with B2C instances:
2626
## Command Topics
2727

2828
- [Code Commands](./code) - Deploy cartridges and manage code versions
29+
- [Job Commands](./jobs) - Execute and monitor jobs, import/export site archives
2930
- [Sites Commands](./sites) - List and manage sites
3031
- [Sandbox Commands](./sandbox) - Create and manage sandboxes
3132
- [MRT Commands](./mrt) - Manage Managed Runtime environments

‎docs/cli/jobs.md‎

Lines changed: 303 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,303 @@
1+
# Job Commands
2+
3+
Commands for executing and monitoring jobs on B2C Commerce instances.
4+
5+
## b2c job run
6+
7+
Execute a job on a B2C Commerce instance.
8+
9+
### Usage
10+
11+
```bash
12+
b2c job run JOBID
13+
```
14+
15+
### Arguments
16+
17+
| Argument | Description | Required |
18+
|----------|-------------|----------|
19+
| `JOBID` | Job ID to execute | Yes |
20+
21+
### Flags
22+
23+
In addition to [global flags](./index#global-flags):
24+
25+
| Flag | Short | Description | Default |
26+
|------|-------|-------------|---------|
27+
| `--wait` | `-w` | Wait for job to complete | `false` |
28+
| `--timeout` | `-t` | Timeout in seconds when waiting | No timeout |
29+
| `--param` | `-P` | Job parameter in format "name=value" (repeatable) | |
30+
| `--no-wait-running` | | Do not wait for running job to finish before starting | `false` |
31+
| `--show-log` | | Show job log on failure | `true` |
32+
33+
### Examples
34+
35+
```bash
36+
# Execute a job
37+
b2c job run my-custom-job
38+
39+
# Execute and wait for completion
40+
b2c job run my-custom-job --wait
41+
42+
# Execute with timeout
43+
b2c job run my-custom-job --wait --timeout 600
44+
45+
# Execute with parameters
46+
b2c job run my-custom-job -P "SiteScope={\"all_storefront_sites\":true}" -P OtherParam=value
47+
48+
# Output as JSON
49+
b2c job run my-custom-job --wait --json
50+
```
51+
52+
### Authentication
53+
54+
This command requires OAuth authentication with OCAPI permissions for the `/jobs` resource.
55+
56+
---
57+
58+
## b2c job wait
59+
60+
Wait for a job execution to complete.
61+
62+
### Usage
63+
64+
```bash
65+
b2c job wait JOBID EXECUTIONID
66+
```
67+
68+
### Arguments
69+
70+
| Argument | Description | Required |
71+
|----------|-------------|----------|
72+
| `JOBID` | Job ID | Yes |
73+
| `EXECUTIONID` | Execution ID to wait for | Yes |
74+
75+
### Flags
76+
77+
In addition to [global flags](./index#global-flags):
78+
79+
| Flag | Short | Description | Default |
80+
|------|-------|-------------|---------|
81+
| `--timeout` | `-t` | Timeout in seconds | No timeout |
82+
| `--poll-interval` | | Polling interval in seconds | `3` |
83+
| `--show-log` | | Show job log on failure | `true` |
84+
85+
### Examples
86+
87+
```bash
88+
# Wait for a job execution
89+
b2c job wait my-job abc123-def456
90+
91+
# Wait with timeout
92+
b2c job wait my-job abc123-def456 --timeout 600
93+
94+
# Wait with custom polling interval
95+
b2c job wait my-job abc123-def456 --poll-interval 5
96+
```
97+
98+
### Authentication
99+
100+
This command requires OAuth authentication with OCAPI permissions for the `/jobs` resource.
101+
102+
---
103+
104+
## b2c job search
105+
106+
Search for job executions on a B2C Commerce instance.
107+
108+
### Usage
109+
110+
```bash
111+
b2c job search
112+
```
113+
114+
### Flags
115+
116+
In addition to [global flags](./index#global-flags):
117+
118+
| Flag | Short | Description | Default |
119+
|------|-------|-------------|---------|
120+
| `--job-id` | `-j` | Filter by job ID | |
121+
| `--status` | | Filter by status (comma-separated: RUNNING,PENDING,OK,ERROR) | |
122+
| `--count` | `-n` | Maximum number of results | `25` |
123+
| `--start` | | Starting index for pagination | `0` |
124+
| `--sort-by` | | Sort by field (start_time, end_time, job_id, status) | `start_time` |
125+
| `--sort-order` | | Sort order (asc, desc) | `desc` |
126+
127+
### Examples
128+
129+
```bash
130+
# Search all recent job executions
131+
b2c job search
132+
133+
# Search for a specific job
134+
b2c job search --job-id my-custom-job
135+
136+
# Search for running or pending jobs
137+
b2c job search --status RUNNING,PENDING
138+
139+
# Get more results
140+
b2c job search --count 50
141+
142+
# Output as JSON
143+
b2c job search --json
144+
```
145+
146+
### Output
147+
148+
The command displays a table of job executions with:
149+
150+
- Execution ID
151+
- Job ID
152+
- Status
153+
- Start Time
154+
155+
### Authentication
156+
157+
This command requires OAuth authentication with OCAPI permissions for the `/job_execution_search` resource.
158+
159+
---
160+
161+
## b2c job import
162+
163+
Import a site archive to a B2C Commerce instance using the `sfcc-site-archive-import` system job.
164+
165+
### Usage
166+
167+
```bash
168+
b2c job import TARGET
169+
```
170+
171+
### Arguments
172+
173+
| Argument | Description | Required |
174+
|----------|-------------|----------|
175+
| `TARGET` | Directory, zip file, or remote filename to import | Yes |
176+
177+
### Flags
178+
179+
In addition to [global flags](./index#global-flags):
180+
181+
| Flag | Short | Description | Default |
182+
|------|-------|-------------|---------|
183+
| `--keep-archive` | `-k` | Keep archive on instance after import | `false` |
184+
| `--remote` | `-r` | Target is a filename already on the instance (in Impex/src/instance/) | `false` |
185+
| `--timeout` | `-t` | Timeout in seconds | No timeout |
186+
| `--show-log` | | Show job log on failure | `true` |
187+
188+
### Examples
189+
190+
```bash
191+
# Import from a local directory (will be zipped automatically)
192+
b2c job import ./my-site-data
193+
194+
# Import from a zip file
195+
b2c job import ./export.zip
196+
197+
# Keep archive on instance after import
198+
b2c job import ./my-site-data --keep-archive
199+
200+
# Import from existing file on instance
201+
b2c job import existing-archive.zip --remote
202+
203+
# With timeout
204+
b2c job import ./my-site-data --timeout 300
205+
```
206+
207+
### Notes
208+
209+
- When importing a directory, it will be automatically zipped before upload
210+
- The archive is uploaded to `Impex/src/instance/` on the instance
211+
- By default, the archive is deleted after successful import (use `--keep-archive` to retain)
212+
213+
### Authentication
214+
215+
This command requires OAuth authentication with OCAPI permissions for the `/jobs` resource and WebDAV access for file upload.
216+
217+
---
218+
219+
## b2c job export
220+
221+
Export a site archive from a B2C Commerce instance using the `sfcc-site-archive-export` system job.
222+
223+
### Usage
224+
225+
```bash
226+
b2c job export
227+
```
228+
229+
### Flags
230+
231+
In addition to [global flags](./index#global-flags):
232+
233+
| Flag | Short | Description | Default |
234+
|------|-------|-------------|---------|
235+
| `--output` | `-o` | Output path for the export | `.` (current directory) |
236+
| `--data-units` | | Data units JSON configuration | |
237+
| `--site` | | Site ID(s) to export (comma-separated, repeatable) | |
238+
| `--site-data` | | Site data types to export (comma-separated) | |
239+
| `--global-data` | | Global data types to export (comma-separated) | |
240+
| `--catalog` | | Catalog ID(s) to export (comma-separated) | |
241+
| `--pricebook` | | Pricebook ID(s) to export (comma-separated) | |
242+
| `--library` | | Library ID(s) to export (comma-separated) | |
243+
| `--inventory` | | Inventory list ID(s) to export (comma-separated) | |
244+
| `--keep-archive` | `-k` | Keep archive on instance after download | `false` |
245+
| `--no-download` | | Do not download archive (implies --keep-archive) | `false` |
246+
| `--zip-only` | | Save as zip file without extracting | `false` |
247+
| `--timeout` | `-t` | Timeout in seconds | No timeout |
248+
| `--show-log` | | Show job log on failure | `true` |
249+
250+
### Examples
251+
252+
```bash
253+
# Export global metadata
254+
b2c job export --global-data meta_data
255+
256+
# Export a site's content and preferences
257+
b2c job export --site RefArch --site-data content,site_preferences
258+
259+
# Export catalogs
260+
b2c job export --catalog storefront-catalog
261+
262+
# Export with custom data units JSON
263+
b2c job export --data-units '{"global_data":{"meta_data":true}}'
264+
265+
# Export to a specific directory
266+
b2c job export --output ./exports
267+
268+
# Keep archive on instance
269+
b2c job export --global-data meta_data --keep-archive
270+
271+
# Output as JSON
272+
b2c job export --global-data meta_data --json
273+
```
274+
275+
### Data Units
276+
277+
The export is configured using "data units" which specify what data to export. You can use convenience flags (`--site`, `--global-data`, etc.) or provide a full JSON configuration with `--data-units`.
278+
279+
#### Site Data Types
280+
281+
When using `--site-data`, available types include:
282+
- `all` - Export all site data
283+
- `content` - Content assets and slots
284+
- `site_preferences` - Site preferences
285+
- `campaigns_and_promotions` - Marketing campaigns
286+
- `customer_groups` - Customer groups
287+
- `payment_methods` - Payment configurations
288+
- And more (see OCAPI documentation)
289+
290+
#### Global Data Types
291+
292+
When using `--global-data`, available types include:
293+
- `all` - Export all global data
294+
- `meta_data` - System and custom object metadata
295+
- `custom_types` - Custom object type definitions
296+
- `preferences` - Global preferences
297+
- `locales` - Locale configurations
298+
- `services` - Service configurations
299+
- And more (see OCAPI documentation)
300+
301+
### Authentication
302+
303+
This command requires OAuth authentication with OCAPI permissions for the `/jobs` resource and WebDAV access for file download.

‎packages/b2c-cli/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,5 @@ yarn.lock
1212
package-lock.json
1313

1414
dw.json
15+
16+
export/

‎packages/b2c-cli/package.json‎

Lines changed: 24 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -70,22 +70,35 @@
7070
"topicSeparator": " ",
7171
"topics": {
7272
"auth": {
73-
"description": "Authentication and token management"
74-
},
75-
"hello": {
76-
"description": "Say hello to the world and others"
73+
"description": "Manage authentication credentials and tokens"
7774
},
7875
"code": {
79-
"description": "Manage cartridge code on instances"
80-
},
81-
"sites": {
82-
"description": "Manage sites on instances"
76+
"description": "Deploy and manage code versions on instances"
8377
},
84-
"sandbox": {
85-
"description": "Manage on-demand sandboxes"
78+
"job": {
79+
"description": "Run jobs and import/export site archives"
8680
},
8781
"mrt": {
88-
"description": "Managed Runtime operations"
82+
"description": "Manage Managed Runtime projects and deployments",
83+
"subtopics": {
84+
"env-var": {
85+
"description": "Manage environment variables on MRT projects"
86+
}
87+
}
88+
},
89+
"ods": {
90+
"description": "Manage On-Demand Sandboxes"
91+
},
92+
"sites": {
93+
"description": "List and inspect storefront sites"
94+
},
95+
"slas": {
96+
"description": "Manage SLAS API clients and credentials",
97+
"subtopics": {
98+
"client": {
99+
"description": "Manage SLAS client configurations"
100+
}
101+
}
89102
}
90103
}
91104
},

0 commit comments

Comments
 (0)