This skill guides you through implementing web service integrations in B2C Commerce using the Service Framework.
Overview
The Service Framework provides a structured way to call external services with:
Feature
Description
Configuration
Service settings managed in Business Manager
Rate Limiting
Automatic throttling to protect external systems
Circuit Breaker
Automatic failure handling to prevent cascade failures
Logging
Communication logging with sensitive data filtering
Mocking
Test services without external calls
Service Types
Type
Use Case
Protocol
HTTP
REST APIs, webhooks
HTTP/HTTPS
HTTPForm
Form submissions
HTTP/HTTPS with form encoding
FTP
File transfers (deprecated)
FTP
SFTP
Secure file transfers
SFTP
SOAP
SOAP web services
HTTP/HTTPS with SOAP
GENERIC
Custom protocols
Any
Service Framework Components
Business Manager Configuration
Services are configured in
Administration > Operations > Services
:
Service Configuration
- General settings (enabled, logging, callbacks)
Service Profile
- Rate limiting and circuit breaker settings
Service Credential
- URL and authentication credentials
Script Components
Component
Purpose
LocalServiceRegistry
Creates service instances
ServiceCallback
Defines request/response handling
Service
Base service with common methods
Result
Response object with status and data
Basic Pattern
'use strict'
;
var
LocalServiceRegistry
=
require
(
'dw/svc/LocalServiceRegistry'
)
;
var
myService
=
LocalServiceRegistry
.
createService
(
'my.service.id'
,
{
/**
* Configure the request before it is sent
*
@param
{
dw
.
svc
.
HTTPService
}
svc
- The service instance
*
@param
{
Object
}
params
- Parameters passed to service.call()
*
@returns
{
string
}
Request body
*/
createRequest
:
function
(
svc
,
params
)
{
svc
.
setRequestMethod
(
'POST'
)
;
svc
.
addHeader
(
'Content-Type'
,
'application/json'
)
;
return
JSON
.
stringify
(
params
)
;
}
,
/**
* Parse the response after a successful call
*
@param
{
dw
.
svc
.
HTTPService
}
svc
- The service instance
*
@param
{
dw
.
net
.
HTTPClient
}
client
- The HTTP client with response
*
@returns
{
Object
}
Parsed response
*/
parseResponse
:
function
(
svc
,
client
)
{
return
JSON
.
parse
(
client
.
text
)
;
}
,
/**
* Filter sensitive data from logs (required for production)
*
@param
{
string
}
msg
- The message to filter
*
@returns
{
string
}
Filtered message
*/
filterLogMessage
:
function
(
msg
)
{
return
msg
.
replace
(
/
(
"api_key"
\s
*
:
\s
*
"
)
[
^
"
]
+
"
/
g
,
'$1***"'
)
;
}
}
)
;
// Call the service
var
result
=
myService
.
call
(
{
key
:
'value'
}
)
;
if
(
result
.
ok
)
{
var
data
=
result
.
object
;
}
else
{
var
error
=
result
.
errorMessage
;
}
Service Callbacks
Callback
Required
Description
createRequest
Yes*
Configure request, return body
parseResponse
Yes*
Parse response, return result object
execute
No
Custom execution logic (replaces default)
initServiceClient
No
Create/configure underlying client
mockCall
No
Return mock response (execute phase only)
mockFull
No
Return mock response (entire call)
filterLogMessage
Recommended
Filter sensitive data from logs
getRequestLogMessage
No
Custom request log message
getResponseLogMessage
No
Custom response log message
*Required unless
execute
is implemented
Result Object
The
call()
method returns a
dw.svc.Result
:
Property
Type
Description
ok
Boolean
True if successful
status
String
"OK", "ERROR", or "SERVICE_UNAVAILABLE"
object
Object
Response from
parseResponse
error
Number
Error code (e.g., HTTP status)
errorMessage
String
Error description
unavailableReason
String
Why service is unavailable
mockResult
Boolean
True if from mock callback
Unavailable Reasons
Reason
Description
TIMEOUT
Call timed out
RATE_LIMITED
Rate limit exceeded
CIRCUIT_BROKEN
Circuit breaker open
DISABLED
Service disabled
CONFIG_PROBLEM
Configuration error
Error Handling
var
result
=
myService
.
call
(
params
)
;
if
(
result
.
ok
)
{
return
result
.
object
;
}
// Handle different error types
switch
(
result
.
status
)
{
case
'SERVICE_UNAVAILABLE'
:
switch
(
result
.
unavailableReason
)
{
case
'RATE_LIMITED'
:
// Retry later
break
;
case
'CIRCUIT_BROKEN'
:
// Service is down, use fallback
break
;
case
'TIMEOUT'
:
// Request timed out
break
;
}
break
;
case
'ERROR'
:
// Check HTTP status code
if
(
result
.
error
===
401
)
{
// Authentication error
}
else
if
(
result
.
error
===
404
)
{
// Resource not found
}
break
;
}
throw
new
Error
(
'Service error: '
+
result
.
errorMessage
)
;
Log Filtering
Production environments require log filtering to prevent sensitive data exposure:
var
myService
=
LocalServiceRegistry
.
createService
(
'my.service'
,
{
createRequest
:
function
(
svc
,
params
)
{
// ... configure request
}
,
parseResponse
:
function
(
svc
,
client
)
{
return
JSON
.
parse
(
client
.
text
)
;
}
,
/**
* Filter sensitive data from all log messages
*/
filterLogMessage
:
function
(
msg
)
{
// Filter API keys
msg
=
msg
.
replace
(
/
api_key=
[
^
&
]
+
/
g
,
'api_key=***'
)
;
// Filter authorization headers
msg
=
msg
.
replace
(
/
Authorization:
\s
*
[
^
\r
\n
]
+
/
gi
,
'Authorization: ***'
)
;
// Filter passwords in JSON
msg
=
msg
.
replace
(
/
(
"password"
\s
*
:
\s
*
"
)
[
^
"
]
+
"
/
g
,
'$1***"'
)
;
return
msg
;
}
,
/**
* Custom request log message (optional)
*/
getRequestLogMessage
:
function
(
request
)
{
// Return custom message or null for default
return
'Request: '
+
request
.
substring
(
0
,
100
)
+
'...'
;
}
,
/**
* Custom response log message (optional)
*/
getResponseLogMessage
:
function
(
response
)
{
// Return custom message or null for default
return
'Response received'
;
}
}
)
;
Mocking Services
Use mock callbacks for testing without external calls:
var
myService
=
LocalServiceRegistry
.
createService
(
'my.service'
,
{
createRequest
:
function
(
svc
,
params
)
{
svc
.
setRequestMethod
(
'GET'
)
;
svc
.
addParam
(
'id'
,
params
.
id
)
;
return
null
;
}
,
parseResponse
:
function
(
svc
,
client
)
{
return
JSON
.
parse
(
client
.
text
)
;
}
,
/**
* Mock the execute phase only (createRequest and parseResponse still run)
*/
mockCall
:
function
(
svc
,
request
)
{
return
{
statusCode
:
200
,
text
:
JSON
.
stringify
(
{
id
:
1
,
name
:
'Mock Data'
}
)
}
;
}
,
/**
* Or mock the entire call (replaces all phases)
*/
mockFull
:
function
(
svc
,
params
)
{
return
{
id
:
params
.
id
,
name
:
'Full Mock Data'
}
;
}
}
)
;
// Force mock mode
myService
.
setMock
(
)
;
var
result
=
myService
.
call
(
{
id
:
123
}
)
;
Service Configuration in Business Manager
Creating a Service
Go to
Administration > Operations > Services
Click
New
under Service Configurations
Fill in:
Service ID
Unique identifier (e.g.,
my.api.service
)
Service Type
HTTP, FTP, SOAP, etc.
Enabled
Check to enable
Profile
Select or create a profile
Credential
Select or create credentials
Communication Log
Enable for debugging
Service Profile Settings
Setting
Description
Timeout
Maximum wait time in milliseconds
Rate Limit
Maximum calls per time unit
Circuit Breaker Enabled
Enable automatic failure handling
Max Circuit Breaker Calls
Calls before circuit opens
Circuit Breaker Interval
Time window for tracking failures
Service Credential Settings
Setting
Description
ID
Credential identifier
URL
Base URL for the service
User
Username for authentication
Password
Password for authentication
Detailed References
HTTP Services
- REST API integrations
FTP/SFTP Services
- File transfer operations
SOAP Services
- SOAP web service integrations
Services XML
- Import/export service configurations
Script API Classes
Class
Description
dw.svc.LocalServiceRegistry
Create service instances
dw.svc.Service
Base service class
dw.svc.HTTPService
HTTP service methods
dw.svc.FTPService
FTP/SFTP service methods
dw.svc.SOAPService
SOAP service methods
dw.svc.Result
Service call result
dw.svc.ServiceConfig
Service configuration
dw.svc.ServiceProfile
Rate limit/circuit breaker config
dw.svc.ServiceCredential
Authentication credentials
dw.net.HTTPClient
Underlying HTTP client
dw.net.FTPClient
Underlying FTP client
dw.net.SFTPClient
Underlying SFTP client