1. Extending Oracle Commerce
  2. Develop Server-Side Extensions
  3. Configure an SSE

Configure an SSE

A server-side extension consists of a directory structure containing code and configuration files.

This section applies to both OSF and Storefront Classic. This section applies to Open Storefront Framework (OSF) and Storefront Classic.

The extension must be packaged as a single ZIP file that can be uploaded through the administration interface. The ZIP file should not be larger than 25 MB. The filename consists of the name of the application plus .zip. If an extension by the same name has already been uploaded, uploading this file will overwrite the existing extension.

The following is an example of the directory structure of an SSE ZIP file:

<extension-name>
   package.json
   config/
      config.json
   lib/
      *.js
   node_modules/
      <modules>
   locales/
      <locale>.json

This section describes how to configure an SSE, using settings available in .json files and in the server extension framework. For more information about SSE configuration management, see Server-Side Extension Configuration Management.

package.json

The top level of an SSE must include a metadata file named package.json containing predefined properties that provide information about the extension. For example: 

{
   "name": "shippingCalculator",
   "version": "0.0.1",  
   "description": "SSE that calls an external shipping calculator service.",  
   "main": "/app/index.js",
   "author": "Fred Smith",  
   "dependencies" : { "config": "latest" },
   "devDependencies" : { "express" : "latest" },
   "authenticatedUrls": [],
   "publicUrls": [
      "/ccstorex/custom/v1/calculateShipping",
   ],
... 
}

The following are key properties whose values you specify in the file:

  • main: Identifies the JavaScript file that is the entry point into the application. This is executed and loads the extension to be run. Required.
  • publicUrls: Lists all the routes for the extension that do not require authentication.
  • authenticatedUrls: Lists the routes that only logged-in users can access. This is typically used for SSEs that implement Admin or Agent endpoints, but it can also be used to require shoppers accessing Store endpoints to be logged in.
  • dependencies: Specifies the application's runtime dependencies. Ensure any modules you list here are also packaged with your application and uploaded to Commerce.
  • devDependencies: Specifies the application's development-only dependencies. These modules should not be included in the uploaded ZIP file.

At least one route must be listed in either publicUrls or authenticatedUrls.

In addition, if your server-side extension needs to call out to any external domains, you must use the package.json file's allowedUrls property to specify an array of these URLs. For example:
"allowedUrls": [
   "https://www.example.com",
   "https://www.example2.com"
  ]

The URLs you specify are added to the list maintained by your Oracle Commerce environment. Calls to these URLs (including any subpaths) are permitted. Calls to domains that are not on this list are blocked. Note that calls from SSEs must use HTTPS and be sent over port 443 or 8443. For sending email, ports 465 (legacy SMTPS) and 587 (STARTTLS) are allowed; you can specify an SMTP server by just its domain name, such as smtp.example.com. SSEs can use a library such as Nodemailer that is capable of sending email through a proxy.

Note: The allowedUrls property replaces the whitelistUrls property that was formerly used for specifying external domains. The whitelistUrls property has been deprecated. If you currently have an SSE that has the whitelistUrls property, you should rename the property to allowedUrls. If you do not rename the property, Commerce will continue to permit access to the domains specified in whitelistUrls. However, if you add the allowedUrls property without removing whitelistUrls, Commerce will ignore whilelistUrls and permit access only to the domains specified in allowedUrls.

Development dependencies

The Oracle Commerce server-side extension framework includes a number of libraries that you can declare as devDependencies for use in developing your application. These libraries include:

  • Express: Node.js web application framework.
  • Body-parser: Middleware that parses incoming request bodies.
  • Jasmine: Development framework for testing JavaScript code.
  • Moment: Tool that parses, validates, manipulates, and displays dates and times in JavaScript.
  • Nconf: Simple key-value store with support for both local and remote storage.
  • Winston: Simple and universal logging library with support for multiple transports.

You should not include any of these libraries in the SSE ZIP file that you upload to Commerce, because they may override the versions of those libraries in the framework.

Environment variables

The extension server framework defines environment variables using the Nconf library. These variables are available to all SSEs running in your environment. Note that you should not include the Nconf library in an SSE's node_modules folder, because this will override the version in the framework and may prevent the SSE from accessing the environment variables.

The following table describes the predefined SSE environment variables:

Variable Name Description
atg.application.credentials Container for token, ID, and name values.
atg.application.token 3rd-party application key used to access the Commerce Admin API; child of atg.application.credentials.
atg.application.id Application ID; child of atg.application.credentials.
atg.application.name Application name; child of atg.application.credentials.
atg.server.url URL of the storefront server.
atg.server.admin.url URL of the administration server.
general:proxy-server Commerce environment’s proxy server.

The following is an example of how to use nconf to access environment variables in your code: 

var nconf = require('nconf');
var storeServerUrl = nconf.get('atg.server.url');
var adminServerUrl = nconf.get('atg.server.admin.url');
var adminToken = nconf.get('atg.application.credentials: atg.application.token');

You can create and manage additional environment variables for your extension server using the Extension Server Environment Variables endpoints in the Admin API. For example, you could create an environment variable called my.custom.variable and access it in your code like this: 

var customVar = nconf.get('my.custom.variable');

config.json

You can use the config.json file in the SSE's top-level config directory to create and initialize properties specific to the SSE. You can use these properties to define additional configuration or to specify data to be passed to endpoints and webhooks that the SSE invokes. For example, the config.json file for an SSE that integrates with a payment gateway might be similar to this: 

{
    "authenticationType": "http_signature",
    "enableLog": true,
    "logFilename": "logging.txt",
    "cardTypes": {
        "VISA": "001",
        "MASTERCARD": "002",
        "AMEX": "003"
        }
}