Configure an SSE
A server-side extension consists of a directory structure containing code and configuration files.
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:
https://cloudcustomerconnect.oracle.com/posts/b43dfc9484
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
.
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"
}
}