Loading...
Loading...
Implement web service integrations in B2C Commerce using LocalServiceRegistry. Use when calling external APIs, configuring service credentials in services.xml, handling HTTP requests/responses, or implementing circuit breakers. Covers HTTP, SOAP, FTP, and SFTP services.
npx skill4agent add salesforcecommercecloud/b2c-developer-tooling b2c-webservices| 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 |
| Type | Use Case | Protocol |
|---|---|---|
| REST APIs, webhooks | HTTP/HTTPS |
| Form submissions | HTTP/HTTPS with form encoding |
| File transfers (deprecated) | FTP |
| Secure file transfers | SFTP |
| SOAP web services | HTTP/HTTPS with SOAP |
| Custom protocols | Any |
| Component | Purpose |
|---|---|
| Creates service instances |
| Defines request/response handling |
| Base service with common methods |
| Response object with status and data |
'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;
}| Callback | Required | Description |
|---|---|---|
| Yes* | Configure request, return body |
| Yes* | Parse response, return result object |
| No | Custom execution logic (replaces default) |
| No | Create/configure underlying client |
| No | Return mock response (execute phase only) |
| No | Return mock response (entire call) |
| Recommended | Filter sensitive data from logs |
| No | Custom request log message |
| No | Custom response log message |
executecall()dw.svc.Result| Property | Type | Description |
|---|---|---|
| Boolean | True if successful |
| String | "OK", "ERROR", or "SERVICE_UNAVAILABLE" |
| Object | Response from |
| Number | Error code (e.g., HTTP status) |
| String | Error description |
| String | Why service is unavailable |
| Boolean | True if from mock callback |
| Reason | Description |
|---|---|
| Call timed out |
| Rate limit exceeded |
| Circuit breaker open |
| Service disabled |
| Configuration error |
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);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';
}
});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 });my.api.service| 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 |
| Setting | Description |
|---|---|
| ID | Credential identifier |
| URL | Base URL for the service |
| User | Username for authentication |
| Password | Password for authentication |
| Class | Description |
|---|---|
| Create service instances |
| Base service class |
| HTTP service methods |
| FTP/SFTP service methods |
| SOAP service methods |
| Service call result |
| Service configuration |
| Rate limit/circuit breaker config |
| Authentication credentials |
| Underlying HTTP client |
| Underlying FTP client |
| Underlying SFTP client |