Implement an SSE

You implement an SSE as a Node.js application that creates custom endpoints to use as targets for Retail Digital Commerce webhook requests.

This section applies to OSF. This section applies to Open Storefront Framework (OSF).

This section describes some key considerations to be aware of when you implement an SSE.

Export the Application

To make the SSE application available in Retail Digital Commerce, you export the Express subapplication object from the /app/index.js module. For example: 

// Export the subapplication to be embedded in the server-side extension
var express = require('express');
var subApplication = express.Router();
module.exports = subApplication;

Implement Logging

The SSE framework includes a system logger that uses Winston with the necessary transports preconfigured. You can access the system logger in your code by including the global.occ.logger variable. (Inside the route definition, you can use either the global.occ.logger or res.locals.logger variable; both variables refer to the same logger.) You can download the logs by using the GET /ccadminx/custom/v1/logs endpoint.

The following example illustrates using the system logger in SSE code:

if(global.occ) {
  global.occ.logger.debug('Loading sample application.');
}
const response = 'hello system logger!!';
app.get('/v1/helloSystemLogger', function(req, res){

if(global.occ) {
  global.occ.logger.debug('Using global occ variable: ' + response);
  res.locals.logger.debug('Using res.locals.logger within the route definition');
  res.status(200).send(response);
} else {
   res.status(500).send('error');
  }
});

Use Supported MIME and File Types

Server-side extensions support the following MIME types for inbound communication:

  • application/json
  • application/xml
  • text/xml
  • application/x-www-form-urlencoded

Template files, images, and other formats are not supported. You can use any MIME type for outbound communication.

An SSE's ZIP file should contain the following file types only:

  • .json
  • .js
  • .pem
  • .txt
  • .properties

SSL certificate files must be in PEM format and be stored in the top-level ssl/ folder of the extension. Each certificate must be in a separate file.

Make Outbound Calls

The extension server runs behind a proxy, and all outbound calls from the extension server must include the proxy details directly or indirectly. The Retail Digital Commerce HTTPS module indirectly includes the proxy details, so you typically should not need to pass them in.

If, however, you are using any other HTTP client libraries (for example, node-fetch or Axios), check the corresponding library documentation to determine whether you need to provide the proxy details. If so, they can be accessed using the following:

const nconf = require ('nconf');
const proxyServer = nconf.get ("general:proxy-server");

Note that if your code includes references to a Node.js proxy module, they should be to the https-proxy-agent module rather than http-proxy-agent.