# Sfcc Script Evaluation > Guide for using the evaluate_script tool to execute JavaScript on SFCC instances via the script debugger Use when this capability is needed. - Skill: `tomevault-io/sfcc-script-evaluation` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/sfcc-script-evaluation` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/sfcc-script-evaluation/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/sfcc-script-evaluation --- # SFCC Script Evaluation Skill This skill documents how to use the `evaluate_script` tool effectively for executing JavaScript code on an SFCC instance via the script debugger. ## Overview The `evaluate_script` tool allows you to execute arbitrary JavaScript code on an SFCC sandbox instance. It works by: 1. Creating a debugger session 2. Setting a breakpoint on a controller 3. Triggering the controller via HTTP 4. Evaluating your expression in the halted context 5. Returning the result and cleaning up ## Required Parameters | Parameter | Required | Default | Description | |-----------|----------|---------|-------------| | `script` | Yes | - | The JavaScript code to execute | | `siteId` | No | `RefArch` | The site ID (accepts either `RefArch` or `Sites-RefArch-Site`) | | `locale` | No | `default` | Storefront locale segment used when triggering the controller (tries without locale first, then retries with `/{locale}` if needed) | | `timeout` | No | `30000` | Maximum execution time in milliseconds | | `breakpointFile` | No | Auto-detected | Custom controller path for breakpoint | | `breakpointLine` | No | `1,10,20,30,40,50` | Specific line for a single breakpoint; if omitted, strategic lines (1,10,20,30,40,50) are used | | `triggerUrl` | No | Auto-detected | Custom storefront URL or path to trigger; site-relative paths are resolved to `https://{hostname}/s/{siteId}/...` | ## Script Syntax Rules ### ✅ DO: Use expressions that return a value The last expression in your script is returned as the result. ```javascript // Simple expressions 1 + 1 // Result: 2 dw.system.Site.current.ID // Result: "RefArchGlobal" ``` ### ❌ DON'T: Use `return` at the top level ```javascript // WRONG - causes compilation error return 1 + 1 // Error: "invalid return" ``` ### ❌ DON'T: Use `var` assignments expecting the variable ```javascript // WRONG - var declarations return null in debugger context var result = {}; result.foo = 'bar'; // Error: Cannot set property "foo" of null ``` ### ✅ DO: Use inline object literals with JSON.stringify ```javascript // CORRECT - inline object literal wrapped in JSON.stringify JSON.stringify({siteId: dw.system.Site.current.ID, locale: request.locale}) // Result: {"siteId":"RefArchGlobal","locale":"en_GB"} ``` ### ✅ DO: Use IIFEs (Immediately Invoked Function Expressions) for complex logic ```javascript // CORRECT - IIFE pattern for multi-step logic (function() { var p = dw.catalog.ProductMgr.getProduct('25518704M'); return JSON.stringify({id: p.ID, name: p.name, online: p.online}); })() // Result: {"id":"25518704M","name":"Pull On Pant","online":true} ``` ### ❌ DON'T: Use `require()` statements ```javascript // WRONG - require() returns null in debugger context var CustomerMgr = require('dw/customer/CustomerMgr'); CustomerMgr.getSiteCustomerList() // Error: Cannot call method "getSiteCustomerList" of null ``` ### ✅ DO: Use global `dw.*` namespace directly ```javascript // CORRECT - access SFCC APIs via global dw namespace dw.customer.CustomerMgr.getSiteCustomerList().ID // Result: "RefArch" ``` ## Accessing SFCC Objects ### Site Information ```javascript // Current site ID dw.system.Site.current.ID // All sites (function() { var sites = dw.system.Site.getAllSites(); var result = []; for (var i = 0; i < sites.size(); i++) { result.push(sites[i].ID); } return JSON.stringify(result); })() // Site preferences (list all custom preference keys) JSON.stringify(Object.keys(dw.system.Site.current.preferences.custom)) // Get specific site preference value dw.system.Site.current.preferences.custom.myPreferenceName ``` ### Products ```javascript // Get product by ID dw.catalog.ProductMgr.getProduct('productId') // Get product details (function() { var p = dw.catalog.ProductMgr.getProduct('25518704M'); if (!p) return 'Product not found'; return JSON.stringify({ id: p.ID, name: p.name, online: p.online, brand: p.brand }); })() // Product custom attributes (function() { var p = dw.catalog.ProductMgr.getProduct('25518704M'); return JSON.stringify(Object.keys(p.custom)); })() ``` ### Customers ```javascript // Site customer list dw.customer.CustomerMgr.getSiteCustomerList().ID // Get customer by ID (requires customer number) dw.customer.CustomerMgr.getCustomerByCustomerNumber('00001234') ``` ### Orders ```javascript // Search orders (always close the iterator!) (function() { var orders = dw.order.OrderMgr.searchOrders( 'orderNo != {0}', 'creationDate desc', '' ); var result = []; var i = 0; while (orders.hasNext() && i < 5) { var o = orders.next(); result.push({ orderNo: o.orderNo, status: o.status.value, total: o.totalGrossPrice.value }); i++; } orders.close(); // IMPORTANT: Always close iterators return JSON.stringify(result); })() ``` ### Request/Session Context ```javascript // Current request locale request.locale // Result: "en_GB" // Session ID session.sessionID // Current customer (if logged in) session.customer ``` ## Working with Collections SFCC collections need special handling - they're not JavaScript arrays. ### Iterating Collections ```javascript // Using size() and index access (function() { var sites = dw.system.Site.getAllSites(); var result = []; for (var i = 0; i < sites.size(); i++) { result.push(sites[i].ID); } return JSON.stringify(result); })() // Using Iterator pattern (function() { var iter = dw.catalog.CatalogMgr.getSiteCatalog().getRoot().getSubCategories(); var result = []; while (iter.hasNext()) { var cat = iter.next(); result.push({id: cat.ID, name: cat.displayName}); } return JSON.stringify(result); })() ``` ### Array Operations ```javascript // Arrays work normally, use JSON.stringify for readable output JSON.stringify([1, 2, 3].map(function(x) { return x * 2; })) // Result: [2,4,6] // Arrow functions are supported JSON.stringify([1, 2, 3].map(x => x * 2)) // Result: [2,4,6] ``` ## Return Value Formatting ### Primitives ```javascript // Strings, numbers, booleans return directly 'hello' // Result: "hello" 42 // Result: 42 true // Result: true ``` ### Objects ```javascript // Raw objects return [object Object] ({foo: 'bar'}) // Result: [object Object] // Use JSON.stringify for readable output JSON.stringify({foo: 'bar'}) // Result: {"foo":"bar"} ``` ### SFCC Objects ```javascript // SFCC objects return their string representation dw.catalog.ProductMgr.getProduct('25518704M') // Result: [Product sku=25518704M] // Access properties directly or use JSON.stringify dw.catalog.ProductMgr.getProduct('25518704M').name // Result: "Pull On Pant" ``` ## Error Handling ### Check for null values ```javascript // WRONG - throws error if product doesn't exist dw.catalog.ProductMgr.getProduct('invalid').name // Error: Cannot read property "name" from null // CORRECT - check for null (function() { var p = dw.catalog.ProductMgr.getProduct('invalid'); return p ? p.name : 'Product not found'; })() // Result: "Product not found" ``` ### Wrap complex logic in try-catch ```javascript (function() { try { var p = dw.catalog.ProductMgr.getProduct('25518704M'); return JSON.stringify({id: p.ID, name: p.name}); } catch (e) { return 'Error: ' + e.message; } })() ``` ## Best Practices Summary 1. **Never use `return` at top level** - use expression evaluation instead 2. **Never use `require()`** - use global `dw.*` namespace 3. **Wrap complex logic in IIFEs** for variable declarations 4. **Use `JSON.stringify()`** for object/array output 5. **Close iterators** after use (OrderMgr.searchOrders, etc.) 6. **Check for null** before accessing properties 7. **Verify API usage** with `get_sfcc_class_info` tool before calling unknown methods ## Common Patterns ### Quick Value Check ```javascript dw.system.Site.current.ID ``` ### Multi-Value Query ```javascript JSON.stringify({ siteId: dw.system.Site.current.ID, locale: request.locale, customerList: dw.customer.CustomerMgr.getSiteCustomerList().ID }) ``` ### Complex Data Retrieval ```javascript (function() { // Your multi-step logic here var result = []; // ... build result ... return JSON.stringify(result); })() ``` ## Troubleshooting | Error | Cause | Solution | |-------|-------|----------| | `invalid return` | Using `return` at top level | Remove `return`, use expression or IIFE | | `Cannot call method of null` | Using `require()` | Use `dw.*` global namespace | | `Cannot set property of null` | `var x = {}` returns null | Use IIFE or inline object literal | | `Timeout waiting for breakpoint` | Wrong siteId or instance unreachable | Verify siteId, check instance connectivity | | `Unexpected token '<'` | Auth/connectivity issue | Check dw.json credentials, verify instance is accessible | | `Unauthorized` / `401` | Username case mismatch | **Username is case-sensitive** - match exactly from BM user | | `No compatible storefront cartridge` | Missing SFRA or SiteGenesis | Deploy app_storefront_base or specify custom breakpoint | ## Pre-Flight Checklist Before using `evaluate_script`: 1. ✅ Valid credentials in dw.json configuration 2. ✅ **Username matches BM user exactly (case-sensitive!)** 3. ✅ Sandbox instance is accessible 4. ✅ Storefront cartridge deployed (app_storefront_base or app_storefront_controllers) 5. ✅ Script uses `dw.*` namespace, not `require()` 6. ✅ Complex logic wrapped in IIFE 7. ✅ Objects/arrays wrapped in `JSON.stringify()` ## Requirements - SFCC sandbox instance - Either `app_storefront_base` (SFRA) or `app_storefront_controllers` (SiteGenesis) deployed - Valid credentials in dw.json configuration - **Important:** Username in dw.json must match BM user exactly (case-sensitive) --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/taurgis) — claim your Tome and manage your conversions.