Implement an SSE
You implement an SSE as a Node.js application that creates custom endpoints to use as targets for Commerce webhook requests.
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 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 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
.