BRAND SETUP GUIDE

This document includes following topics:

• Branding
• Implementation
• CASE I : Node HTTP Server is on same setup as OHS
• CASE II : Node HTTP Server is different setup from OHS
• Handling Assets

 

Branding

Branding describes the process of applying a product or company brand to the user interface. One can regard it as "theming with the goal to represent a certain product/company on the user interface". So the typical changes are the same as theming, with the only difference that certain visual styles and entities are directly derived from a product or company brand.

Implementation

Branding in OBDX is implemented in terms of changing CSS and changing the image resources.

CSS compilation is done using node-sass [NodeJS package].

Largely speaking, when a brand is created, the variables taken from user input provide the overriding variables for the scss which is then compiled to CSS by node-sass. The image resources are taken as zip file and extracted alongside brand artifacts.

There are two basic requirements:

• Node HTTP Server to generate brand artifacts.
• HTTP Server to serve brand artifacts*.

*Not needed if Node HTTP server is on same setup as OHS.In this case, OHS can be used to serve the artifacts.

There are two cases:

• The Node HTTP Server is on same setup as OHS. [Recommended]
• The Node HTTP Server is on different setup from OHS.

Out of these, the first option is recommended as it enables sharing of SCSS resources and eliminates the need of a separate HTTP server required to serve brand artifacts.

CASE I : Node HTTP Server is on same setup as OHS

• Install NodeJS on your system.
• Make sure to update npm by running
  • $ npm install npm@latest -g

You need root access to install packages globally

• Set npm proxy
  • $ npm config set proxy <your-proxy-here>
• Navigate to channel directory which is managed by OHS.

Note: All paths from hereon will be with respect to channel directory

• Create a folder brand
  • $ mkdir brand
• Navigate to brand-engine
  • $ cd brand-engine
• Install the required packages $ npm install
• Configure the variables in properties.json according to your implementation.
• Port: The port number at which the Node HTTP Server will listen.
• Logs: The path to create debug logs. Defaults to same directory.
• URLs: The list of URLs accepted by Node HTTP Server. Usually, no need to modify.
• Roles: The list of roles (directories) for which you wish to create brand.
• Files:
• sass-main: The location of main.scss
• assets: The location at which assets will be deployed.
• Image Base Path: The root path from where images will be resolved.
• Brand Base Path: The root path from where images called via CSS will be resolved.
• The Node HTTP Server is started in clustered mode with 4 instances by default. To change the number of instances or to change the mode, modify process.yaml
• Start the Node HTTP Server using
  • $ npm start

Some common commands for server management:

$ npm run stop --- Stop the server

$ npm run restart --- Restart the server

For more details, refer documentation for pm2.

• The OHS will server all requests to /brand directory and no need to create any additional HTTP Server.
• In System Configuration setup, set Content Publisher URL as URL of the Node HTTP Server and Brand Base URL as OHS server URL till with /brand

CASE II : Node HTTP Server are on different setup from Application HTTP server (OHS)

• Follow steps 1 – 10 of first case as mentioned above with exception of step 4.
• For step 4, you need to copy or checkout channel directory and follow the subsequent steps for the aforementioned directory.
• After completing the above steps, keep only following folders:
• admin/sass/
• corporate/sass/
• framework/sass/
• index/sass/
• retail/sass/
• third-party/sass/
• wallet/sass
• brand-engine/
• brand/
• Start HTTP Server of your choice, OHS/Apache or any other HTTP Server with document root being the channel directory. This HTTP server must run on the same setup as the node server. This HTTP server will render the styles to the Application HTTP Server (OHS) which will be on a different set up.
• Make sure your HTTP Server sets the header Access-Control-Allow-Origin: <origin>, where <origin> is the parent OHS.
• If you have enabled Content Security Policy [refer Security Guide], add the new host as <allowed host> in obdx.conf and restart the OHS. For more detail, refer OHS setup guide and Security Guide
• In System Configuration setup, set Content Publisher URL as URL of the Node Server and Content Server URL as URL of the HTTP server present on the same setup and append /brand to it. But these urls are to be configured through the system configuration screen of the Application HTTP Server (OHS) where the changes are to be reflected.

Handling Assets

Assets upload is for uploading image assets for branding purposes. For adding a new image asset to override the default image asset available, following steps need to be followed.

• Whitelist the image assets as specified in framework/js/constants/brand-assets.js. Keep in mind that only the images whitelisted in above file can be overridden via branding.
• Place the changed files which you wish to update in the same directory structure as images folder. Create a zip file at the root.

For example, if you wish to override the bank logo, the corresponding image file is images/common/logo.svg

Related section in framework/js/constants/brand-assets.js will look like

And folder structure of the zip file would be, assuming zip is named images.zip (zip name is not an issue).

Home