@salesforce/b2c-cli 2.3.0 → 2.4.0

package/content/guidance/b2c/b2c-custom-job-steps/references/CHUNK-ORIENTED.md

@@ -0,0 +1,377 @@
+# Chunk-Oriented Job Steps Reference
+
+Complete patterns for chunk-oriented job steps.
+
+## When to Use
+
+- Product exports/imports
+- Order processing
+- Customer data sync
+- Inventory updates
+- Any bulk data operation with countable items
+
+**Important:** Chunk-oriented steps **cannot** define custom exit status. They always finish with either **OK** or **ERROR**.
+
+## Basic Structure
+
+```javascript
+'use strict';
+
+var iterator;
+
+exports.beforeStep = function (parameters, stepExecution) {
+    // Initialize: open files, start queries
+};
+
+exports.getTotalCount = function (parameters, stepExecution) {
+    return iterator.count;
+};
+
+exports.read = function (parameters, stepExecution) {
+    if (iterator.hasNext()) {
+        return iterator.next();
+    }
+};
+
+exports.process = function (item, parameters, stepExecution) {
+    // Transform item
+    return transformedItem;
+};
+
+exports.write = function (items, parameters, stepExecution) {
+    // Write chunk
+};
+
+exports.afterStep = function (success, parameters, stepExecution) {
+    // Cleanup
+};
+```
+
+## Product Export Example
+
+```javascript
+'use strict';
+
+var ProductMgr = require('dw/catalog/ProductMgr');
+var File = require('dw/io/File');
+var FileWriter = require('dw/io/FileWriter');
+var Logger = require('dw/system/Logger');
+
+var log = Logger.getLogger('job', 'ProductExport');
+var products;
+var writer;
+
+exports.beforeStep = function (parameters, stepExecution) {
+    var outputPath = parameters.OutputFile || '/export/products.csv';
+    var outputFile = new File(File.IMPEX + outputPath);
+
+    // Ensure the directory exists. dw.io.File has no parent accessor, so
+    // derive the directory from the path and create it directly.
+    var dirPath = outputPath.substring(0, outputPath.lastIndexOf('/'));
+    new File(File.IMPEX + dirPath).mkdirs();
+
+    writer = new FileWriter(outputFile, 'UTF-8');
+    writer.writeLine('ID,Name,Brand,Price,Online');
+
+    // Query all products
+    products = ProductMgr.queryAllSiteProducts();
+
+    log.info('Starting product export');
+};
+
+exports.getTotalCount = function (parameters, stepExecution) {
+    return products.count;
+};
+
+exports.read = function (parameters, stepExecution) {
+    if (products.hasNext()) {
+        return products.next();
+    }
+};
+
+exports.process = function (product, parameters, stepExecution) {
+    // Skip masters (export variants only) or filter as needed
+    if (product.master) {
+        return;  // Filter out
+    }
+
+    // Extract and transform data
+    return {
+        id: product.ID,
+        name: escapeCsv(product.name || ''),
+        brand: product.brand ? escapeCsv(product.brand) : '',
+        price: product.priceModel.price ? product.priceModel.price.value : 0,
+        online: product.online ? 'Y' : 'N'
+    };
+};
+
+exports.write = function (items, parameters, stepExecution) {
+    for (var i = 0; i < items.size(); i++) {
+        var item = items.get(i);
+        writer.writeLine([
+            item.id,
+            item.name,
+            item.brand,
+            item.price,
+            item.online
+        ].join(','));
+    }
+};
+
+exports.afterStep = function (success, parameters, stepExecution) {
+    if (products) {
+        products.close();
+    }
+    if (writer) {
+        writer.close();
+    }
+
+    if (success) {
+        log.info('Product export completed successfully');
+    } else {
+        log.error('Product export failed');
+    }
+};
+
+function escapeCsv(str) {
+    if (str.indexOf(',') >= 0 || str.indexOf('"') >= 0) {
+        return '"' + str.replace(/"/g, '""') + '"';
+    }
+    return str;
+}
+```
+
+## Order Processing Example
+
+```javascript
+'use strict';
+
+var OrderMgr = require('dw/order/OrderMgr');
+var Transaction = require('dw/system/Transaction');
+var Logger = require('dw/system/Logger');
+
+var log = Logger.getLogger('job', 'OrderProcess');
+var orders;
+
+exports.beforeStep = function (parameters, stepExecution) {
+    var status = parameters.OrderStatus || 'NEW';
+
+    // Query orders by status
+    orders = OrderMgr.searchOrders(
+        'status = {0}',
+        'creationDate asc',
+        require('dw/order/Order')[status]
+    );
+
+    log.info('Found ' + orders.count + ' orders to process');
+};
+
+exports.getTotalCount = function (parameters, stepExecution) {
+    return orders.count;
+};
+
+exports.read = function (parameters, stepExecution) {
+    if (orders.hasNext()) {
+        return orders.next();
+    }
+};
+
+exports.process = function (order, parameters, stepExecution) {
+    // Validate order can be processed
+    if (order.paymentStatus.value !== require('dw/order/Order').PAYMENT_STATUS_PAID) {
+        log.warn('Skipping order ' + order.orderNo + ' - not paid');
+        return;  // Filter out
+    }
+
+    return order;
+};
+
+exports.write = function (orders, parameters, stepExecution) {
+    for (var i = 0; i < orders.size(); i++) {
+        var order = orders.get(i);
+
+        Transaction.wrap(function () {
+            // Update order status
+            order.setExportStatus(require('dw/order/Order').EXPORT_STATUS_EXPORTED);
+            log.info('Processed order: ' + order.orderNo);
+        });
+    }
+};
+
+exports.afterStep = function (success, parameters, stepExecution) {
+    if (orders) {
+        orders.close();
+    }
+};
+```
+
+## Customer Sync Example
+
+```javascript
+'use strict';
+
+var CustomerMgr = require('dw/customer/CustomerMgr');
+var HTTPClient = require('dw/net/HTTPClient');
+var Transaction = require('dw/system/Transaction');
+var Logger = require('dw/system/Logger');
+
+var log = Logger.getLogger('job', 'CustomerSync');
+var customers;
+var apiUrl;
+var apiKey;
+
+exports.beforeStep = function (parameters, stepExecution) {
+    apiUrl = parameters.APIEndpoint;
+    apiKey = parameters.APIKey;
+
+    // Query customers modified since last sync
+    var lastSync = parameters.LastSyncDate;
+    if (lastSync) {
+        customers = CustomerMgr.searchProfiles(
+            'lastModified >= {0}',
+            'lastModified asc',
+            new Date(lastSync)
+        );
+    } else {
+        customers = CustomerMgr.searchProfiles('', 'lastModified asc');
+    }
+};
+
+exports.getTotalCount = function (parameters, stepExecution) {
+    return customers.count;
+};
+
+exports.read = function (parameters, stepExecution) {
+    if (customers.hasNext()) {
+        return customers.next();
+    }
+};
+
+exports.process = function (profile, parameters, stepExecution) {
+    return {
+        customerId: profile.customerNo,
+        email: profile.email,
+        firstName: profile.firstName,
+        lastName: profile.lastName,
+        lastModified: profile.lastModified.toISOString()
+    };
+};
+
+exports.write = function (items, parameters, stepExecution) {
+    var http = new HTTPClient();
+    http.setTimeout(30000);
+    http.setRequestHeader('Authorization', 'Bearer ' + apiKey);
+    http.setRequestHeader('Content-Type', 'application/json');
+
+    // Convert Java List to array
+    var payload = [];
+    for (var i = 0; i < items.size(); i++) {
+        payload.push(items.get(i));
+    }
+
+    try {
+        http.open('POST', apiUrl + '/customers/batch');
+        http.send(JSON.stringify({ customers: payload }));
+
+        if (http.statusCode >= 200 && http.statusCode < 300) {
+            log.info('Synced ' + payload.length + ' customers');
+        } else {
+            log.error('API error: ' + http.statusCode);
+            throw new Error('API returned ' + http.statusCode);
+        }
+    } catch (e) {
+        log.error('Sync error: ' + e.message);
+        throw e;  // Causes step to fail
+    }
+};
+
+exports.afterStep = function (success, parameters, stepExecution) {
+    if (customers) {
+        customers.close();
+    }
+};
+```
+
+## Chunk Lifecycle
+
+1. `beforeStep()` - Called once at start
+2. For each chunk:
+   - `beforeChunk()` - Before chunk (optional)
+   - `read()` - Called repeatedly until returns nothing
+   - `process()` - Called for each item from read()
+   - `write()` - Called with chunk of processed items
+   - `afterChunk()` - After chunk (optional)
+3. `afterStep(success)` - Called once at end
+
+## Chunk Size Considerations
+
+| Chunk Size | Pros | Cons |
+|------------|------|------|
+| Small (10-50) | More frequent progress updates | Higher overhead |
+| Medium (100-500) | Good balance | Default choice |
+| Large (1000+) | Less overhead | Less granular progress |
+
+## Transaction Handling
+
+Two approaches:
+
+**1. transactional="true" in steptypes.json:**
+```json
+{
+    "transactional": "true",
+    "chunk-size": 100
+}
+```
+Each chunk wrapped in single transaction. Rollback on error.
+
+**2. Manual Transaction.wrap():**
+```javascript
+exports.write = function (items, parameters, stepExecution) {
+    for (var i = 0; i < items.size(); i++) {
+        var item = items.get(i);
+        Transaction.wrap(function () {
+            // Per-item transaction
+        });
+    }
+};
+```
+More control, item-level error handling.
+
+## steptypes.json for Chunk Steps
+
+```json
+{
+    "step-types": {
+        "chunk-script-module-step": [
+            {
+                "@type-id": "custom.ProductExport",
+                "@supports-parallel-execution": "true",
+                "@supports-site-context": "true",
+                "@supports-organization-context": "false",
+                "description": "Export products to CSV",
+                "module": "my_cartridge/cartridge/scripts/steps/productExport.js",
+                "before-step-function": "beforeStep",
+                "total-count-function": "getTotalCount",
+                "read-function": "read",
+                "process-function": "process",
+                "write-function": "write",
+                "after-step-function": "afterStep",
+                "chunk-size": 100,
+                "transactional": "false",
+                "timeout-in-seconds": 3600,
+                "parameters": {
+                    "parameter": [
+                        {
+                            "@name": "OutputFile",
+                            "@type": "string",
+                            "@required": "false",
+                            "default-value": "/export/products.csv",
+                            "description": "Output file path"
+                        }
+                    ]
+                }
+            }
+        ]
+    }
+}
+```

package/content/guidance/b2c/b2c-custom-job-steps/references/JOBS-XML.md

@@ -0,0 +1,212 @@
+# jobs.xml Reference (Job Definitions)
+
+`steptypes.json` makes a step *type* available; a **job definition** (`jobs.xml`) is what actually creates a runnable, schedulable job out of one or more steps. This is the missing link between *defining* steps and *running* a job: without a job definition there is no job for `b2c job run` to execute or for Business Manager to schedule.
+
+You author `jobs.xml` and import it with the CLI:
+
+```bash
+b2c job import ./my-job-archive
+```
+
+`jobs.xml` lives at the **root of a site import archive** (alongside `services.xml`, `meta/`, `sites/`, …):
+
+```
+my-job-archive/
+└── jobs.xml          # <-- archive root
+```
+
+After import, the job appears in **Business Manager > Administration > Operations > Jobs** and can be triggered with `b2c job run <job-id>` (see the `b2c-cli:b2c-job` skill).
+
+## Namespace & Schema
+
+Use the jobs impex namespace exactly. The schema is `jobs.xsd`.
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<jobs xmlns="http://www.demandware.com/xml/impex/jobs/2015-07-01">
+    <!-- one or more <job> elements -->
+</jobs>
+```
+
+## Document Structure (element order matters)
+
+A `<job>` child elements **must appear in this order** (enforced by the XSD):
+
+```
+<job>
+  <description>?        (0..1)
+  <parameters>?         (0..1)  job-level parameters
+  (<flow> | <split>)*   (0..n)  one or more step flows
+  <rules>?              (0..1)  on-running / on-retry / on-exit notifications
+  <triggers>            (1..1)  REQUIRED — see below
+</job>
+```
+
+| Element | Required | Notes |
+|---------|----------|-------|
+| `<job job-id="...">` | Yes | `job-id` attribute is required and unique; it is the name you pass to `b2c job run`. |
+| `<description>` | No | Free text (max 4000 chars). |
+| `<parameters>` | No | Job-level parameters; steps can reference them via `job-parameter-ref`. |
+| `<flow>` / `<split>` | No* | Contains the ordered `<step>` elements. A job with no flow does nothing. |
+| `<rules>` | No | Hanging-job / retry / exit email notifications. |
+| **`<triggers>`** | **Yes** | **Required by the schema.** A `jobs.xml` without `<triggers>` fails import validation. Use `<run-once>` for an on-demand/manually-run job. |
+
+## Minimal Single-Step Job
+
+The smallest valid definition: one flow, one step referencing a custom step type, and the **required `<triggers>`** element. `<run-once>` registers the job for manual/on-demand execution (you still run it with `b2c job run`).
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<jobs xmlns="http://www.demandware.com/xml/impex/jobs/2015-07-01">
+    <job job-id="MyNightlyExport">
+        <description>Exports products to a CSV feed</description>
+        <flow>
+            <context site-id="RefArch"/>
+            <step step-id="ExportStep" type="custom.ProductExport">
+                <parameters>
+                    <parameter name="OutputFile">/export/products.csv</parameter>
+                    <parameter name="OnlineOnly">true</parameter>
+                </parameters>
+            </step>
+        </flow>
+        <triggers>
+            <run-once enabled="false">
+                <date>2025-01-01</date>
+                <time>00:00:00.000Z</time>
+            </run-once>
+        </triggers>
+    </job>
+</jobs>
+```
+
+## Step Element
+
+```xml
+<step step-id="UniqueStepId" type="custom.ProductExport" enforce-restart="false">
+    <description>...</description>?
+    <parameters>?
+        <parameter name="ParamName">value</parameter>
+        <parameter name="OtherParam" job-parameter-ref="GlobalParam"/>
+    </parameters>
+    <rules>?
+        <on-exit status="ERROR"><stop-job/></on-exit>
+    </rules>
+</step>
+```
+
+| Attribute / element | Required | Notes |
+|---------------------|----------|-------|
+| `step-id` | Yes | Unique within the flow. |
+| **`type`** | **Yes** | **References the step type to run.** This is the key distinction from `steptypes.json`: in `jobs.xml` you use the attribute **`type`** (e.g. `type="custom.ProductExport"`); the value matches the **`@type-id`** declared in `steptypes.json` for custom steps, or a built-in/system step `type-id` (e.g. `ImportCatalog`, `ExecuteScriptModule`). |
+| `<parameters>/<parameter name="...">` | No | Per-step parameter values. The `name` must match a `@name` declared in the step type's `parameters` in `steptypes.json`. The value is the element text. |
+| `job-parameter-ref` | No | On a `<parameter>`, binds this step parameter to a job-level `<parameter>` instead of a literal value (lets one job parameter feed many steps). |
+| `<rules>/<on-exit status="...">` | No | Per-step flow control: `<stop/>`, `<stop-job/>`, `<stop-flow/>`, or `<continue next-step="..."/>` keyed on the step's exit status code. |
+
+> **`type` (jobs.xml) vs `@type-id` (steptypes.json)** — a common stumbling block. `steptypes.json` *declares* a step type with `"@type-id": "custom.ProductExport"`. `jobs.xml` *uses* it with `<step type="custom.ProductExport">`. They must match exactly (custom type-ids start with `custom.`).
+
+## Multi-Step Job
+
+Steps run in document order within a flow. Use `<context site-id="...">` to scope a site-aware flow; omit it (or use a `<split>`) for organization-scoped steps.
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<jobs xmlns="http://www.demandware.com/xml/impex/jobs/2015-07-01">
+    <job job-id="OrderFulfillmentSync">
+        <parameters>
+            <parameter name="Site">RefArch</parameter>
+        </parameters>
+        <flow>
+            <context site-id="RefArch"/>
+            <step step-id="PullOrders" type="custom.PullOpenOrders">
+                <parameters>
+                    <parameter name="SiteId" job-parameter-ref="Site"/>
+                </parameters>
+                <rules>
+                    <on-exit status="ERROR"><stop-job/></on-exit>
+                </rules>
+            </step>
+            <step step-id="ExportToOMS" type="custom.ExportOrdersToOMS">
+                <parameters>
+                    <parameter name="BatchSize">100</parameter>
+                </parameters>
+            </step>
+        </flow>
+        <triggers>
+            <run-once enabled="false">
+                <date>2025-01-01</date>
+                <time>00:00:00.000Z</time>
+            </run-once>
+        </triggers>
+    </job>
+</jobs>
+```
+
+## Triggers (required)
+
+`<triggers>` is **mandatory** and holds exactly one of `<run-once>` or `<run-recurring>`.
+
+### run-once (on-demand / manual)
+
+Use for jobs you trigger from the CLI or Business Manager rather than on a schedule. `enabled="false"` keeps the one-time scheduled fire from auto-running; you still run it manually.
+
+```xml
+<triggers>
+    <run-once enabled="false">
+        <date>2025-01-01</date>
+        <time>00:00:00.000Z</time>
+    </run-once>
+</triggers>
+```
+
+### run-recurring (scheduled)
+
+```xml
+<triggers>
+    <run-recurring enabled="true">
+        <recurrence>
+            <date-from>2025-01-01</date-from>
+            <start-time>02:00:00.000Z</start-time>
+            <interval>1d</interval>
+            <day-of-week>
+                <weekday>Monday</weekday>
+                <weekday>Wednesday</weekday>
+                <weekday>Friday</weekday>
+            </day-of-week>
+        </recurrence>
+    </run-recurring>
+</triggers>
+```
+
+| `<recurrence>` child | Required | Notes |
+|----------------------|----------|-------|
+| `<date-from>` | Yes | Start date (`YYYY-MM-DD`). |
+| `<date-to>` | No | Optional end date. |
+| `<start-time>` | Yes | Time of day (`HH:MM:SS.SSSZ`). |
+| `<interval>` | No | e.g. `1d`, `30m`, `1h` (max 10 chars). |
+| `<day-of-week>/<weekday>` | No | One or more of `Monday`…`Sunday`. |
+
+## Importing & Running
+
+```bash
+# import the archive containing jobs.xml (waits for completion by default)
+b2c job import ./my-job-archive
+
+# verify / run the job after import
+b2c job run MyNightlyExport --wait --show-log
+```
+
+If the import fails with a schema validation error, the most common causes are a **missing `<triggers>` element**, children out of the required order, or a `<step type="...">` whose value doesn't match a declared `@type-id` (custom step types must be imported via `steptypes.json` in a deployed cartridge first). Use `b2c job import ./my-job-archive --show-log` to see the validation detail.
+
+## Common Pitfalls
+
+- **Missing `<triggers>`** — the element is required by the XSD; import fails without it. For a manually-run job, use `<run-once enabled="false">`.
+- **Child order** — `description → parameters → flow/split → rules → triggers`. Out-of-order children fail validation.
+- **`type` vs `@type-id`** — `jobs.xml` uses the `type` attribute on `<step>`; it must match the `@type-id` in `steptypes.json` (or a system step type-id).
+- **Custom step not deployed** — the cartridge carrying the step's `steptypes.json` and module must be on the active code version (and on the cartridge path) before the job can resolve the step type.
+- **Wrong context scope** — site-scoped steps need a `<context site-id="...">`; org-scoped steps must not be placed under a site context. This must agree with `@supports-site-context` / `@supports-organization-context` in `steptypes.json`.
+
+## Related
+
+- [steptypes.json Reference](STEPTYPES-JSON.md) — declaring the step types referenced by `<step type="...">`.
+- `b2c-cli:b2c-job` — running the imported job (`b2c job run`) and importing the archive (`b2c job import`).
+- `b2c-cli:b2c-site-import-export` — site archive structure (`jobs.xml` is a root-level archive file).