@salesforce/b2c-cli 2.3.1 → 2.4.0

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

@@ -0,0 +1,344 @@
+# Task-Oriented Job Steps Reference
+
+Complete patterns for task-oriented job steps.
+
+## When to Use
+
+- FTP file transfers
+- Import/export operations
+- Report generation
+- External API calls
+- Cleanup operations
+- Any non-iterable task
+
+## Basic Structure
+
+```javascript
+'use strict';
+
+var Status = require('dw/system/Status');
+
+exports.execute = function (parameters, stepExecution) {
+    // Your logic here
+    return new Status(Status.OK);
+};
+```
+
+## Status Codes
+
+Custom status codes work **only** with `Status.OK`. Custom codes with `Status.ERROR` are replaced with ERROR.
+
+```javascript
+// Custom OK codes work - these are useful for flow transitions
+return new Status(Status.OK, 'NO_DATA', 'No files found');
+return new Status(Status.OK, 'PARTIAL', 'Some items processed');
+
+// ERROR always becomes ERROR - custom code is ignored
+return new Status(Status.ERROR, null, 'Something failed');  // Code will be ERROR
+```
+
+## Step Execution Context
+
+```javascript
+exports.execute = function (parameters, stepExecution) {
+    // Access job information
+    var jobId = stepExecution.jobExecution.jobID;
+    var stepId = stepExecution.stepID;
+    var stepTypeId = stepExecution.stepTypeID;
+
+    // Read a declared step parameter by name
+    var batchSize = stepExecution.getParameterValue('BatchSize');
+};
+```
+
+## FTP Download Example
+
+```javascript
+'use strict';
+
+var Status = require('dw/system/Status');
+var FTPClient = require('dw/net/FTPClient');
+var File = require('dw/io/File');
+var Logger = require('dw/system/Logger');
+
+var log = Logger.getLogger('job', 'FTPDownload');
+
+exports.execute = function (parameters, stepExecution) {
+    var host = parameters.Host;
+    var username = parameters.Username;
+    var password = parameters.Password;
+    var remoteFile = parameters.RemoteFile;
+    var localPath = parameters.LocalPath;
+
+    var ftp = new FTPClient();
+
+    try {
+        // Connect
+        log.info('Connecting to ' + host);
+        ftp.connect(host, username, password);
+
+        if (!ftp.connected) {
+            return new Status(Status.ERROR, 'CONNECT_FAILED', 'Failed to connect to FTP server');
+        }
+
+        // Download file
+        log.info('Downloading ' + remoteFile);
+        var localFile = new File(File.IMPEX + localPath);
+        var success = ftp.getBinary(remoteFile, localFile);
+
+        if (!success) {
+            return new Status(Status.ERROR, 'DOWNLOAD_FAILED', 'Failed to download file');
+        }
+
+        log.info('Download complete: ' + localFile.fullPath);
+        return new Status(Status.OK);
+
+    } catch (e) {
+        log.error('FTP error: ' + e.message);
+        return new Status(Status.ERROR, 'FTP_ERROR', e.message);
+
+    } finally {
+        if (ftp.connected) {
+            ftp.disconnect();
+        }
+    }
+};
+```
+
+## SFTP Example
+
+```javascript
+'use strict';
+
+var Status = require('dw/system/Status');
+var SFTPClient = require('dw/net/SFTPClient');
+var File = require('dw/io/File');
+var Logger = require('dw/system/Logger');
+
+var log = Logger.getLogger('job', 'SFTPUpload');
+
+exports.execute = function (parameters, stepExecution) {
+    var host = parameters.Host;
+    var port = parameters.Port || 22;
+    var username = parameters.Username;
+    var password = parameters.Password;
+    var localPath = parameters.LocalFile;
+    var remotePath = parameters.RemotePath;
+
+    var sftp = new SFTPClient();
+
+    try {
+        sftp.connect(host, port, username, password);
+
+        if (!sftp.connected) {
+            return new Status(Status.ERROR, 'CONNECT_FAILED');
+        }
+
+        var localFile = new File(File.IMPEX + localPath);
+        if (!localFile.exists()) {
+            return new Status(Status.ERROR, 'FILE_NOT_FOUND', 'Local file not found');
+        }
+
+        sftp.putBinary(remotePath, localFile);
+        log.info('Uploaded: ' + localFile.name + ' to ' + remotePath);
+
+        return new Status(Status.OK);
+
+    } finally {
+        if (sftp.connected) {
+            sftp.disconnect();
+        }
+    }
+};
+```
+
+## HTTP/REST API Example
+
+```javascript
+'use strict';
+
+var Status = require('dw/system/Status');
+var HTTPClient = require('dw/net/HTTPClient');
+var Logger = require('dw/system/Logger');
+
+var log = Logger.getLogger('job', 'APISync');
+
+exports.execute = function (parameters, stepExecution) {
+    var apiUrl = parameters.APIUrl;
+    var apiKey = parameters.APIKey;
+
+    var http = new HTTPClient();
+    http.setTimeout(30000);
+    http.setRequestHeader('Authorization', 'Bearer ' + apiKey);
+    http.setRequestHeader('Content-Type', 'application/json');
+
+    try {
+        http.open('POST', apiUrl);
+        http.send(JSON.stringify({ action: 'sync', timestamp: new Date().toISOString() }));
+
+        var statusCode = http.statusCode;
+        var responseText = http.text;
+
+        if (statusCode >= 200 && statusCode < 300) {
+            log.info('API sync successful');
+            return new Status(Status.OK);
+        } else {
+            log.error('API error: ' + statusCode + ' - ' + responseText);
+            return new Status(Status.ERROR, 'API_ERROR', 'HTTP ' + statusCode);
+        }
+
+    } catch (e) {
+        log.error('HTTP error: ' + e.message);
+        return new Status(Status.ERROR, 'HTTP_ERROR', e.message);
+    }
+};
+```
+
+## File Processing Example
+
+```javascript
+'use strict';
+
+var Status = require('dw/system/Status');
+var File = require('dw/io/File');
+var FileReader = require('dw/io/FileReader');
+var FileWriter = require('dw/io/FileWriter');
+var Logger = require('dw/system/Logger');
+
+var log = Logger.getLogger('job', 'FileProcessor');
+
+exports.execute = function (parameters, stepExecution) {
+    var inputPath = parameters.InputFile;
+    var outputPath = parameters.OutputFile;
+
+    var inputFile = new File(File.IMPEX + inputPath);
+    if (!inputFile.exists()) {
+        return new Status(Status.ERROR, 'FILE_NOT_FOUND', 'Input file not found');
+    }
+
+    var outputFile = new File(File.IMPEX + outputPath);
+    var reader;
+    var writer;
+
+    try {
+        reader = new FileReader(inputFile);
+        writer = new FileWriter(outputFile);
+
+        var line;
+        var lineCount = 0;
+
+        while ((line = reader.readLine()) !== null) {
+            // Process line
+            var processed = line.toUpperCase();  // Example transformation
+            writer.writeLine(processed);
+            lineCount++;
+        }
+
+        log.info('Processed ' + lineCount + ' lines');
+        return new Status(Status.OK);
+
+    } finally {
+        if (reader) reader.close();
+        if (writer) writer.close();
+    }
+};
+```
+
+## Cleanup Example
+
+```javascript
+'use strict';
+
+var Status = require('dw/system/Status');
+var File = require('dw/io/File');
+var Logger = require('dw/system/Logger');
+
+var log = Logger.getLogger('job', 'FileCleanup');
+
+exports.execute = function (parameters, stepExecution) {
+    var directory = parameters.Directory;
+    var maxAgeHours = parameters.MaxAgeHours || 24;
+
+    var folder = new File(File.IMPEX + directory);
+    if (!folder.exists() || !folder.directory) {
+        return new Status(Status.ERROR, 'INVALID_PATH', 'Directory not found');
+    }
+
+    var files = folder.listFiles();
+    var cutoffTime = Date.now() - (maxAgeHours * 60 * 60 * 1000);
+    var deletedCount = 0;
+
+    for (var i = 0; i < files.length; i++) {
+        var file = files[i];
+        if (!file.directory && file.lastModified() < cutoffTime) {
+            file.remove();
+            deletedCount++;
+            log.info('Deleted: ' + file.name);
+        }
+    }
+
+    log.info('Cleanup complete. Deleted ' + deletedCount + ' files.');
+    return new Status(Status.OK, 'OK', 'Deleted ' + deletedCount + ' files');
+};
+```
+
+## steptypes.json for Task Steps
+
+```json
+{
+    "step-types": {
+        "script-module-step": [
+            {
+                "@type-id": "custom.FTPDownload",
+                "@supports-parallel-execution": "false",
+                "@supports-site-context": "true",
+                "@supports-organization-context": "false",
+                "description": "Download file from FTP server",
+                "module": "my_cartridge/cartridge/scripts/steps/ftpDownload.js",
+                "function": "execute",
+                "timeout-in-seconds": 600,
+                "parameters": {
+                    "parameter": [
+                        {
+                            "@name": "Host",
+                            "@type": "string",
+                            "@required": "true",
+                            "description": "FTP server hostname"
+                        },
+                        {
+                            "@name": "Username",
+                            "@type": "string",
+                            "@required": "true"
+                        },
+                        {
+                            "@name": "Password",
+                            "@type": "string",
+                            "@required": "true"
+                        },
+                        {
+                            "@name": "RemoteFile",
+                            "@type": "string",
+                            "@required": "true",
+                            "description": "Remote file path"
+                        },
+                        {
+                            "@name": "LocalPath",
+                            "@type": "string",
+                            "@required": "true",
+                            "description": "Local path (relative to IMPEX)"
+                        }
+                    ]
+                },
+                "status-codes": {
+                    "status": [
+                        { "@code": "OK", "description": "Download successful" },
+                        { "@code": "ERROR", "description": "Download failed" },
+                        { "@code": "CONNECT_FAILED", "description": "Connection failed" },
+                        { "@code": "DOWNLOAD_FAILED", "description": "File download failed" }
+                    ]
+                }
+            }
+        ]
+    }
+}
+```

package/content/guidance/b2c/b2c-custom-objects/SKILL.md

@@ -0,0 +1,327 @@
+---
+name: b2c-custom-objects
+description: Store and query custom business data using CustomObjectMgr, OCAPI Data API, and Shopper Custom Objects API. Use this skill whenever the user needs to create, read, update, or search custom object instances, build processing queues with status fields, choose between site-scoped and organization-scoped storage, or query custom objects with bool/term filters. Also use when persisting non-standard data -- even if they just say 'store config per site' or 'query my custom data'.
+---
+
+# B2C Custom Objects
+
+Custom objects store business data that doesn't fit into standard system objects. They support both site-scoped and organization-scoped (global) data, with full CRUD operations via Script API and OCAPI.
+
+## When to Use Custom Objects
+
+| Use Case | Example |
+|----------|---------|
+| Business configuration | Store configuration per site or globally |
+| Integration data | Cache external system responses |
+| Custom entities | Loyalty tiers, custom promotions, vendor data |
+| Temporary processing | Job processing queues, import staging |
+
+## Custom Object Types
+
+Custom objects are defined in Business Manager under **Administration > Site Development > Custom Object Types**. Each type has:
+
+- **ID**: Unique identifier (e.g., `CustomConfig`)
+- **Key Attribute**: Primary key field for lookups
+- **Attributes**: Custom attributes for data storage
+- **Scope**: Site-scoped or organization-scoped (global)
+
+## Script API (CustomObjectMgr)
+
+### Getting Custom Objects
+
+```javascript
+var CustomObjectMgr = require('dw/object/CustomObjectMgr');
+
+// Get a single custom object by type and key
+var config = CustomObjectMgr.getCustomObject('CustomConfig', 'myConfigKey');
+
+if (config) {
+    var value = config.custom.configValue;
+}
+```
+
+### Creating Custom Objects
+
+```javascript
+var CustomObjectMgr = require('dw/object/CustomObjectMgr');
+var Transaction = require('dw/system/Transaction');
+
+Transaction.wrap(function() {
+    // Create new custom object (type, keyValue)
+    var obj = CustomObjectMgr.createCustomObject('CustomConfig', 'newKey');
+    obj.custom.configValue = 'myValue';
+    obj.custom.isActive = true;
+});
+```
+
+### Querying Custom Objects
+
+```javascript
+var CustomObjectMgr = require('dw/object/CustomObjectMgr');
+
+// Query with attribute filter
+var objects = CustomObjectMgr.queryCustomObjects(
+    'CustomConfig',                    // Type
+    'custom.isActive = {0}',           // Query (uses positional params)
+    'creationDate desc',               // Sort order
+    true                               // Parameter value for {0}
+);
+
+while (objects.hasNext()) {
+    var obj = objects.next();
+    // Process object
+}
+objects.close();
+```
+
+### Deleting Custom Objects
+
+```javascript
+var CustomObjectMgr = require('dw/object/CustomObjectMgr');
+var Transaction = require('dw/system/Transaction');
+
+Transaction.wrap(function() {
+    var obj = CustomObjectMgr.getCustomObject('CustomConfig', 'keyToDelete');
+    if (obj) {
+        CustomObjectMgr.remove(obj);
+    }
+});
+```
+
+### Getting All Objects of a Type
+
+```javascript
+var CustomObjectMgr = require('dw/object/CustomObjectMgr');
+
+// Get all objects of a type
+var allConfigs = CustomObjectMgr.getAllCustomObjects('CustomConfig');
+
+while (allConfigs.hasNext()) {
+    var config = allConfigs.next();
+    // Process
+}
+allConfigs.close();
+```
+
+## CustomObjectMgr API Reference
+
+| Method | Description |
+|--------|-------------|
+| `getCustomObject(type, keyValue)` | Get single object by type and key |
+| `createCustomObject(type, keyValue)` | Create new object (within transaction) |
+| `remove(object)` | Delete object (within transaction) |
+| `queryCustomObjects(type, query, sortString, ...args)` | Query with filters |
+| `getAllCustomObjects(type)` | Get all objects of a type |
+| `describe(type)` | Get metadata about the custom object type |
+
+## OCAPI Data API
+
+### Get Custom Object
+
+```http
+GET /s/-/dw/data/v25_6/custom_objects/{object_type}/{key}
+Authorization: Bearer {token}
+```
+
+**Note:** Use `/s/{site_id}/dw/data/v25_6/custom_objects/...` for site-scoped objects, or `/s/-/dw/data/v25_6/custom_objects/...` for organization-scoped (global) objects.
+
+### Create Custom Object
+
+```http
+PUT /s/-/dw/data/v25_6/custom_objects/{object_type}/{key}
+Authorization: Bearer {token}
+Content-Type: application/json
+
+{
+    "key_property": "myKey",
+    "c_configValue": "myValue",
+    "c_isActive": true
+}
+```
+
+### Update Custom Object
+
+```http
+PATCH /s/-/dw/data/v25_6/custom_objects/{object_type}/{key}
+Authorization: Bearer {token}
+Content-Type: application/json
+
+{
+    "c_configValue": "updatedValue"
+}
+```
+
+### Delete Custom Object
+
+```http
+DELETE /s/-/dw/data/v25_6/custom_objects/{object_type}/{key}
+Authorization: Bearer {token}
+```
+
+### Search Custom Objects
+
+```http
+POST /s/-/dw/data/v25_6/custom_objects_search/{object_type}
+Authorization: Bearer {token}
+Content-Type: application/json
+
+{
+    "query": {
+        "bool_query": {
+            "must": [
+                { "term_query": { "fields": ["c_isActive"], "operator": "is", "values": [true] } }
+            ]
+        }
+    },
+    "select": "(**)",
+    "sorts": [{ "field": "creation_date", "sort_order": "desc" }],
+    "start": 0,
+    "count": 25
+}
+```
+
+### Search Query Types
+
+| Query Type | Description | Example |
+|------------|-------------|---------|
+| `term_query` | Exact match / comparison | `{"fields": ["c_status"], "operator": "is", "values": ["active"]}` |
+| `text_query` | Full-text search | `{"fields": ["c_name"], "search_phrase": "test"}` |
+| `filtered_query` | Query plus a filter — use with `range_filter` for ranges | `{"query": {"match_all_query": {}}, "filter": {"range_filter":{"field": "c_count", "from": 1, "to": 10}}}` |
+| `bool_query` | Combine queries | `{"must": [...], "should": [...], "must_not": [...]}` |
+| `match_all_query` | Match all records | `{}` |
+
+## Shopper Custom Objects API (SCAPI)
+
+For read-only access from storefronts, use the Shopper Custom Objects API. This requires specific OAuth scopes.
+
+### Get Custom Object (Shopper)
+
+```http
+GET https://{shortCode}.api.commercecloud.salesforce.com/custom-object/shopper-custom-objects/v1/organizations/{organizationId}/custom-objects/{objectType}/{key}?siteId={siteId}
+Authorization: Bearer {shopper_token}
+```
+
+### Required Scopes
+
+For the Shopper Custom Objects API, configure these scopes in your SLAS client:
+
+- `sfcc.shopper-custom-objects` - Global read access to all custom object types
+- `sfcc.shopper-custom-objects.{objectType}` - Type-specific read access
+
+**Note:** SLAS clients can have a maximum of 20 custom object scopes.
+
+The custom object type must also be enabled for shopper access in Business Manager.
+
+### Searchable System Fields
+
+All custom objects have these system fields available for OCAPI search queries:
+
+- `creation_date` - When the object was created (Date)
+- `last_modified` - When the object was last modified (Date)
+- `key_value_string` - String key value
+- `key_value_integer` - Integer key value
+- `site_id` - Site identifier (for site-scoped objects)
+
+## Best Practices
+
+### Do
+
+- Use transactions for create/update/delete operations
+- Close query iterators when done (`objects.close()`)
+- Use meaningful key values for efficient lookups
+- Index frequently queried attributes
+- Use site-scoped objects for site-specific data
+- Use organization-scoped objects for shared configuration
+
+### Don't
+
+- Store sensitive data without encryption
+- Create excessive custom object types
+- Use custom objects for high-volume transactional data
+- Forget to handle null returns from `getCustomObject()`
+- Leave query iterators open (causes resource leaks)
+
+## Common Patterns
+
+### Configuration Store
+
+```javascript
+var CustomObjectMgr = require('dw/object/CustomObjectMgr');
+var Site = require('dw/system/Site');
+
+function getConfig(key, defaultValue) {
+    var configKey = Site.current.ID + '_' + key;
+    var obj = CustomObjectMgr.getCustomObject('SiteConfig', configKey);
+
+    if (obj && obj.custom.value !== null) {
+        return JSON.parse(obj.custom.value);
+    }
+    return defaultValue;
+}
+
+function setConfig(key, value) {
+    var Transaction = require('dw/system/Transaction');
+    var configKey = Site.current.ID + '_' + key;
+
+    Transaction.wrap(function() {
+        var obj = CustomObjectMgr.getCustomObject('SiteConfig', configKey);
+        if (!obj) {
+            obj = CustomObjectMgr.createCustomObject('SiteConfig', configKey);
+        }
+        obj.custom.value = JSON.stringify(value);
+    });
+}
+```
+
+### Processing Queue
+
+```javascript
+var CustomObjectMgr = require('dw/object/CustomObjectMgr');
+var Transaction = require('dw/system/Transaction');
+
+// Add to queue
+function enqueue(data) {
+    var key = 'job_' + Date.now() + '_' + Math.random().toString(36).substr(2, 9);
+    Transaction.wrap(function() {
+        var obj = CustomObjectMgr.createCustomObject('JobQueue', key);
+        obj.custom.data = JSON.stringify(data);
+        obj.custom.status = 'pending';
+    });
+}
+
+// Process queue
+function processQueue() {
+    var pending = CustomObjectMgr.queryCustomObjects(
+        'JobQueue',
+        'custom.status = {0}',
+        'creationDate asc',
+        'pending'
+    );
+
+    while (pending.hasNext()) {
+        var job = pending.next();
+        Transaction.wrap(function() {
+            job.custom.status = 'processing';
+        });
+
+        try {
+            var data = JSON.parse(job.custom.data);
+            processJob(data);
+
+            Transaction.wrap(function() {
+                CustomObjectMgr.remove(job);
+            });
+        } catch (e) {
+            Transaction.wrap(function() {
+                job.custom.status = 'failed';
+                job.custom.error = e.message;
+            });
+        }
+    }
+    pending.close();
+}
+```
+
+## Detailed References
+
+- [OCAPI Search Queries](references/OCAPI-SEARCH.md) - Full search query syntax and examples