sfcc-dev-mcp 1.0.15 → 1.0.19

package/ai-instructions/skills/sfcc-job-development/references/TASK-ORIENTED.md

@@ -0,0 +1,257 @@
+# Task-Oriented Job Steps Reference
+
+Complete reference for task-oriented (script-module-step) job development in SFCC.
+
+## When to Use Task-Oriented Jobs
+
+Choose task-oriented jobs for:
+- Single configuration file downloads
+- Single API calls to external services
+- Quick, targeted database updates
+- Tasks where calculating progress is impractical
+
+## Script Structure
+
+```javascript
+'use strict';
+
+var Status = require('dw/system/Status');
+var Transaction = require('dw/system/Transaction');
+var Logger = require('dw/system/Logger');
+
+/**
+ * Main function for task-oriented job step
+ * @param {Object} parameters - Parameters from Business Manager
+ * @param {dw.job.JobStepExecution} stepExecution - Job context and logging
+ * @returns {dw.system.Status} - Exit status
+ */
+exports.execute = function (parameters, stepExecution) {
+    var logger = Logger.getLogger('jobs', 'TaskOrientedJob');
+    
+    try {
+        logger.info('Starting job with parameters: {0}', JSON.stringify(parameters));
+        
+        var result = performBusinessLogic(parameters, logger);
+        
+        if (result.success) {
+            logger.info('Job completed successfully');
+            return new Status(Status.OK);
+        } else {
+            logger.warn('Job completed with warnings: {0}', result.message);
+            return new Status(Status.OK, 'OK', result.message);
+        }
+        
+    } catch (e) {
+        logger.error('Job failed with error: {0}', e.message);
+        return new Status(Status.ERROR, 'ERROR', e.message);
+    }
+};
+
+function performBusinessLogic(parameters, logger) {
+    // Implementation here
+    return { success: true, message: 'Operation completed' };
+}
+```
+
+## Status Control for Flow Management
+
+```javascript
+exports.execute = function (parameters, stepExecution) {
+    var logger = Logger.getLogger('jobs', 'StatusControlJob');
+    
+    try {
+        var inputFile = new File(File.IMPEX + parameters.fileName);
+        
+        if (!inputFile.exists()) {
+            logger.info('Input file not found: {0}', parameters.fileName);
+            // Use OK status with descriptive message for conditional flow control
+            return new Status(Status.OK, 'OK', 'Input file was not present - skipping processing');
+        }
+        
+        if (inputFile.length() === 0) {
+            logger.info('Input file is empty: {0}', parameters.fileName);
+            return new Status(Status.OK, 'OK', 'No data to process - file is empty');
+        }
+        
+        // Process file...
+        return new Status(Status.OK, 'OK', 'File processed successfully');
+        
+    } catch (e) {
+        logger.error('Processing failed: {0}', e.message);
+        return new Status(Status.ERROR, 'ERROR', e.message);
+    }
+};
+```
+
+## Transaction Management
+
+```javascript
+// RECOMMENDED: Use Transaction.wrap for automatic lifecycle management
+exports.execute = function (parameters, stepExecution) {
+    var logger = Logger.getLogger('jobs', 'TransactionJob');
+    
+    try {
+        var category = CatalogMgr.getCategory(parameters.categoryID);
+        var products = ProductMgr.queryProductsInCatalog(category.getCatalog());
+        var updateCount = 0;
+        
+        // Transaction.wrap handles begin/commit/rollback automatically
+        Transaction.wrap(function () {
+            while (products.hasNext()) {
+                var product = products.next();
+                if (product.isOnline() && product.isAssignedToCategory(category)) {
+                    product.setOnlineFlag(false);
+                    updateCount++;
+                }
+            }
+        });
+        
+        products.close();
+        logger.info('Updated {0} products', updateCount);
+        return new Status(Status.OK);
+        
+    } catch (e) {
+        logger.error('Transaction failed: {0}', e.message);
+        return new Status(Status.ERROR);
+    }
+};
+```
+
+## Status Codes
+
+```javascript
+// Success
+return new Status(Status.OK);
+return new Status(Status.OK, 'CUSTOM_CODE', 'Custom message');
+
+// Error
+return new Status(Status.ERROR);
+return new Status(Status.ERROR, null, 'Error message');
+```
+
+**Important:** Custom status codes work **only** with OK status. If you use a custom code with ERROR status, it is replaced with ERROR. Custom status codes cannot contain commas, wildcards, leading/trailing whitespace, or exceed 100 characters.
+
+## steptypes.json Configuration
+
+```json
+{
+    "step-types": {
+        "script-module-step": [
+            {
+                "@type-id": "custom.DeactivateProducts",
+                "@supports-site-context": true,
+                "@supports-organization-context": false,
+                "description": "Deactivates all online products in a specified category",
+                "module": "plugin_examplecartridge/cartridge/scripts/jobs/deactivateProducts.js",
+                "function": "execute",
+                "transactional": false,
+                "timeout-in-seconds": 900,
+                "parameters": {
+                    "parameter": [
+                        {
+                            "@name": "categoryID",
+                            "@type": "string",
+                            "@required": true,
+                            "description": "ID of the category containing products to deactivate"
+                        },
+                        {
+                            "@name": "dryRun",
+                            "@type": "boolean", 
+                            "@required": false,
+                            "description": "If true, only logs what would be deactivated"
+                        }
+                    ]
+                },
+                "status-codes": {
+                    "status": [
+                        { "@code": "OK", "description": "Products deactivated successfully" },
+                        { "@code": "ERROR", "description": "An error occurred during processing" }
+                    ]
+                }
+            }
+        ]
+    }
+}
+```
+
+## Attribute Reference
+
+| Attribute | Required | Description | Default |
+|-----------|----------|-------------|---------|
+| `@type-id` | Yes | Unique ID (must start with `custom.`, max 100 chars) | - |
+| `@supports-parallel-execution` | No | Allow parallel execution | `true` |
+| `@supports-site-context` | No | Available in site-scoped jobs | `true` |
+| `@supports-organization-context` | No | Available in org-scoped jobs | `true` |
+| `module` | Yes | Path to script module | - |
+| `function` | Yes | Function name to execute | `execute` |
+| `transactional` | No | Wrap in single transaction | `false` |
+| `timeout-in-seconds` | No | Step timeout (recommended to set) | - |
+
+**Context Constraints:** `@supports-site-context` and `@supports-organization-context` cannot both be `true` or both be `false`.
+
+## External Service Integration
+
+```javascript
+var ServiceRegistry = require('dw/svc/ServiceRegistry');
+
+exports.execute = function (parameters, stepExecution) {
+    var logger = Logger.getLogger('jobs', 'ServiceJob');
+    
+    try {
+        var service = ServiceRegistry.get('MyExternalService');
+        var result = service.call({
+            action: parameters.action,
+            data: parameters.data
+        });
+        
+        if (result.isOk()) {
+            logger.info('Service call successful');
+            return new Status(Status.OK);
+        } else {
+            logger.warn('Service call failed: {0}', result.getErrorMessage());
+            return new Status(Status.ERROR, 'ERROR', result.getErrorMessage());
+        }
+    } catch (e) {
+        logger.error('Service error: {0}', e.message);
+        return new Status(Status.ERROR, 'ERROR', e.message);
+    }
+};
+```
+
+## Idempotent Job Design
+
+```javascript
+exports.execute = function (parameters, stepExecution) {
+    var logger = Logger.getLogger('jobs', 'IdempotentJob');
+    
+    // Check for previous successful run
+    var statusFile = new File(File.IMPEX + 'status/' + parameters.jobRunID + '.complete');
+    if (statusFile.exists()) {
+        logger.info('Job already completed successfully. Skipping.');
+        return new Status(Status.OK, 'ALREADY_COMPLETED');
+    }
+    
+    try {
+        // Create processing flag
+        var processingFile = new File(File.IMPEX + 'status/' + parameters.jobRunID + '.processing');
+        var writer = new FileWriter(processingFile);
+        writer.writeLine(new Date().toISOString());
+        writer.close();
+        
+        // Perform business logic...
+        
+        // Mark job as completed
+        var completeWriter = new FileWriter(statusFile);
+        completeWriter.writeLine(new Date().toISOString());
+        completeWriter.close();
+        
+        // Clean up processing flag
+        processingFile.remove();
+        
+        return new Status(Status.OK);
+    } catch (e) {
+        logger.error('Job failed: {0}', e.message);
+        return new Status(Status.ERROR, 'ERROR', e.message);
+    }
+};
+```

package/ai-instructions/skills/sfcc-localization/SKILL.md

@@ -0,0 +1,92 @@
+````skill
+---
+name: sfcc-localization
+description: Guide for localizing templates, forms, and content in Salesforce B2C Commerce. Use this when asked to implement multi-language support, resource bundles, locale-specific content, or internationalization features.
+---
+
+# Localization Skill
+
+This skill guides you through localizing B2C Commerce storefronts for multiple languages and regions.
+
+## Quick Checklist
+SFCC localization at a glance:
+
+| Area | Approach |
+|------|----------|
+| Templates | Single template set + resource bundles |
+| Forms | Shared XML + localized labels/errors |
+| Static assets | Locale-specific folders when assets contain text |
+| Product/content | Use localizable attributes and content assets |
+
+## Locale Basics
+
+- Format: `{language}_{country}` (e.g., `en_US`, `fr_CA`)
+- Fallback chain example: `fr_CA` → `fr` → default bundle
+- Property files **must** be UTF-8
+
+## Core Principles
+
+1) No hardcoded strings (templates, controllers, JS).  
+2) Use parameters instead of concatenation for dynamic text.  
+3) Keep bundles organized by feature (account, checkout, search).  
+4) Drive dates/currency/numbers from locale settings.  
+5) Keep locale switching consistent in URLs/navigation.
+
+## Minimal Examples
+
+```html
+<!-- Template text -->
+<h1>${Resource.msg('account.title', 'account', null)}</h1>
+<p>${Resource.msgf('cart.itemCount', 'cart', null, pdict.cart.items)}</p>
+
+<!-- Form label via resource key (in XML) -->
+<field formid="email" label="form.email.label" ... />
+
+<!-- Locale-aware static asset -->
+<img src="${URLUtils.staticURL('/images/buttons/submit.png')}" alt="Submit"/>
+```
+
+## Common Pitfalls
+
+- Hardcoded UI text in templates or client JS
+- Concatenated strings instead of parameterized messages
+- Missing UTF-8 encoding on `.properties`
+- Locale switcher that drops query/path context
+- Remote includes serving localized fragments without proper cache keys
+
+## Where to Go Next (References)
+
+- [Resource Bundles](references/RESOURCE-BUNDLES.md)
+- [Static Files](references/STATIC-FILES.md)
+- [Forms Localization](references/FORMS-LOCALIZATION.md)
+- [Controllers](references/CONTROLLERS.md)
+- [Locale Switching](references/LOCALE-SWITCHING.md)
+- [Formatting](references/FORMATTING.md)
+- [JavaScript Localization](references/JAVASCRIPT-LOCALIZATION.md)
+- [Properties & Encoding](references/PROPERTIES-ENCODING.md)
+- [Testing Localization](references/TESTING.md)
+- [Localization Patterns](references/PATTERNS.md)
+
+## MCP Documentation Tools
+
+```javascript
+search_sfcc_classes("Locale")
+get_sfcc_class_info("dw.util.Locale")
+get_sfcc_class_info("dw.web.Resource")
+get_sfcc_class_info("dw.util.StringUtils")
+```
+// Get Locale class documentation
+get_sfcc_class_info("dw.util.Locale")
+
+// Get Resource bundle documentation  
+get_sfcc_class_info("dw.web.Resource")
+
+// Get StringUtils for formatting
+get_sfcc_class_info("dw.util.StringUtils")
+```
+
+## Detailed Reference
+
+- [Localization Patterns](references/PATTERNS.md) - Complete patterns and examples for resource bundles, templates, controllers, and JavaScript
+
+````

package/ai-instructions/skills/sfcc-localization/references/CONTROLLERS.md

@@ -0,0 +1,63 @@
+# Controller Localization
+
+## Accessing Current Locale
+
+```javascript
+var Locale = require('dw/util/Locale');
+server.get('Show', function (req, res, next) {
+  var current = Locale.getLocale(req.locale.id);
+  res.render('mytemplate', {
+    locale: req.locale.id,
+    language: current.language,
+    country: current.country
+  });
+  next();
+});
+```
+
+## Locale-Specific Logic
+
+```javascript
+server.get('Checkout', function (req, res, next) {
+  var locale = req.locale.id;
+  var dateFormat = locale.startsWith('en_US') ? 'MM/dd/yyyy' : 'dd/MM/yyyy';
+  res.render('checkout', { dateFormat: dateFormat });
+  next();
+});
+```
+
+## Localized Errors / JSON Responses
+
+```javascript
+var Resource = require('dw/web/Resource');
+server.post('Submit', function (req, res, next) {
+  if (!server.forms.getForm('profile').valid) {
+    res.json({ success: false, message: Resource.msg('error.form.invalid', 'error', 'Please correct the errors') });
+    return next();
+  }
+  res.json({ success: true, message: Resource.msg('message.saved', 'common', 'Saved successfully') });
+  next();
+});
+```
+
+## Email Templates
+
+```javascript
+var Template = require('dw/util/Template');
+var Mail = require('dw/net/Mail');
+var HashMap = require('dw/util/HashMap');
+var Resource = require('dw/web/Resource');
+
+function sendOrderConfirmation(order, locale) {
+  var template = new Template('mail/orderconfirmation', locale);
+  var model = new HashMap();
+  model.put('order', order);
+
+  var content = template.render(model).text;
+  var mail = new Mail();
+  mail.addTo(order.customerEmail);
+  mail.setSubject(Resource.msg('email.order.subject', 'email', null));
+  mail.setContent(content, 'text/html', 'UTF-8');
+  mail.send();
+}
+```

package/ai-instructions/skills/sfcc-localization/references/FORMATTING.md

@@ -0,0 +1,29 @@
+# Locale-Aware Formatting
+
+## Currency
+
+```javascript
+var Money = require('dw/value/Money');
+var StringUtils = require('dw/util/StringUtils');
+var price = new Money(99.99, 'USD');
+var formatted = StringUtils.formatMoney(price); // Uses current locale
+```
+
+```html
+<isprint value="${product.priceModel.price}" style="CURRENCY"/>
+```
+
+## Dates
+
+```javascript
+var StringUtils = require('dw/util/StringUtils');
+var Calendar = require('dw/util/Calendar');
+var date = new Calendar();
+StringUtils.formatCalendar(date, 'yyyy-MM-dd'); // ISO
+StringUtils.formatCalendar(date, 'MMMM d, yyyy'); // Locale-aware
+```
+
+## Guidelines
+
+- Drive date/number formats from locale, not assumptions.
+- Keep currency tied to site/currency settings; avoid manual symbols.

package/ai-instructions/skills/sfcc-localization/references/FORMS-LOCALIZATION.md

@@ -0,0 +1,33 @@
+# Forms Localization
+
+## Form Definition
+
+```xml
+<form xmlns="http://www.demandware.com/xml/form/2008-04-19">
+  <field formid="email" label="form.email.label" type="string"
+         mandatory="true"
+         missing-error="form.email.required"
+         parse-error="form.email.invalid"/>
+</form>
+```
+
+## Resource Bundles
+
+```properties
+# forms.properties
+form.email.label=Email Address
+form.email.required=Email is required
+form.email.invalid=Please enter a valid email address
+```
+
+```properties
+# forms_fr.properties
+form.email.label=Adresse e-mail
+form.email.required=L'email est requis
+form.email.invalid=Veuillez entrer une adresse e-mail valide
+```
+
+## Guidelines
+
+- Form labels/errors must use resource keys; never hardcode text in XML.
+- Keep keys grouped by form for clarity.

package/ai-instructions/skills/sfcc-localization/references/JAVASCRIPT-LOCALIZATION.md

@@ -0,0 +1,41 @@
+# JavaScript Localization
+
+## Passing Strings to the Client
+
+```html
+<script>
+window.resources = {
+  cart: {
+    addSuccess: '${Resource.msg('cart.add.success', 'cart', 'Added to cart')}',
+    addError: '${Resource.msg('cart.add.error', 'cart', 'Error adding to cart')}'
+  },
+  common: {
+    loading: '${Resource.msg('label.loading', 'common', 'Loading...')}',
+    error: '${Resource.msg('error.general', 'error', 'An error occurred')}'
+  }
+};
+</script>
+```
+
+## Using in JS
+
+```javascript
+function addToCart(productId) {
+  showLoading(window.resources.common.loading);
+  $.ajax({
+    url: '/Cart-AddProduct',
+    data: { pid: productId },
+    success: function (response) {
+      showMessage(response.success ? window.resources.cart.addSuccess : (response.message || window.resources.cart.addError));
+    },
+    error: function () {
+      showMessage(window.resources.common.error);
+    }
+  });
+}
+```
+
+## Guidelines
+
+- Never hardcode UI strings in client JS; source them from server bundles.
+- Keep the client payload minimal—send only strings that are actually used.

package/ai-instructions/skills/sfcc-localization/references/LOCALE-SWITCHING.md

@@ -0,0 +1,35 @@
+# Locale Switching
+
+## Locale-Aware URLs
+
+```html
+<a href="${URLUtils.url('Product-Show', 'pid', 'ABC123')}">View Product</a>
+<a href="${URLUtils.url(new URLAction('Product-Show', 'MySite', 'fr'))}">Voir le produit</a>
+```
+
+## Language Switcher Snippet
+
+```html
+<isscript>
+  var Site = require('dw/system/Site');
+  var URLAction = require('dw/web/URLAction');
+  var URLUtils = require('dw/web/URLUtils');
+  var Locale = require('dw/util/Locale');
+</isscript>
+<ul class="language-switcher">
+  <isloop items="${Site.current.allowedLocales}" var="localeId">
+    <isscript>
+      var locale = new Locale(localeId);
+      var url = URLUtils.url(new URLAction('Home-Show', Site.current.ID, localeId));
+    </isscript>
+    <li class="${request.locale == localeId ? 'active' : ''}">
+      <a href="${url}">${locale.displayLanguage}</a>
+    </li>
+  </isloop>
+</ul>
+```
+
+## Notes
+
+- Allowed locales come from Business Manager (Sites > Manage Sites > Locale Settings).
+- Ensure navigation/stateful URLs include the locale segment or parameter consistently.