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:

•Creating a debugger session
•Setting a breakpoint on a controller
•Triggering the controller via HTTP
•Evaluating your expression in the halted context
•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

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

•Never use return at top level - use expression evaluation instead
•Never use require() - use global dw.* namespace
•Wrap complex logic in IIFEs for variable declarations
•Use JSON.stringify() for object/array output
•Close iterators after use (OrderMgr.searchOrders, etc.)
•Check for null before accessing properties
•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:

•✅ Valid credentials in dw.json configuration
•✅ Username matches BM user exactly (case-sensitive!)
•✅ Sandbox instance is accessible
•✅ Storefront cartridge deployed (app_storefront_base or app_storefront_controllers)
•✅ Script uses dw.* namespace, not require()
•✅ Complex logic wrapped in IIFE
•✅ 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)

SFCC Script Evaluation Skill

Overview

Required Parameters

Script Syntax Rules

✅ DO: Use expressions that return a value

❌ DON'T: Use return at the top level

❌ DON'T: Use var assignments expecting the variable

✅ DO: Use inline object literals with JSON.stringify

✅ DO: Use IIFEs (Immediately Invoked Function Expressions) for complex logic

❌ DON'T: Use require() statements

✅ DO: Use global dw.* namespace directly

Accessing SFCC Objects

Site Information

Products

Customers

Orders

Request/Session Context

Working with Collections

Iterating Collections

Array Operations

Return Value Formatting

Primitives

Objects

SFCC Objects

Error Handling

Check for null values

Wrap complex logic in try-catch

Best Practices Summary

Common Patterns

Quick Value Check

Multi-Value Query

Complex Data Retrieval

Troubleshooting

Pre-Flight Checklist

Requirements

❌ DON'T: Use `return` at the top level

❌ DON'T: Use `var` assignments expecting the variable

❌ DON'T: Use `require()` statements

✅ DO: Use global `dw.*` namespace directly