Introduction

Intershop's Omni-Channel Services Toolset (OCST) is a collection of frameworks that enable fast, standardized development of business Web applications. Based on open-source technologies, the OCST is decoupled from the Intershop 7/Intershop Commerce Management core platform. It uses the REST API to access data and commerce functionality.

A reference implementation which demonstrates the functionality of this toolset is the Intershop Contact Center . The Contact Center is an application that provides a base set of Customer Relationship Management (CRM) functionality. It is intended to be used by specially trained personnel in order to manage the relationship with customers. It includes:

• Customer Management
  • Manage customers master data
  • Manage account information (activation, reactivation, password)
• Offer, Order Management
  • Provide customers specific discounts
  • Placement and editing of orders for customer by representative (including quick-order)
  • Support quoting process
• Contact/Request Management
  • Logging and tracking of contacts (reason, duration, solution)
  • Support of multichannel contacts (call, chat)

The Contact Center is a standalone application. It is connected to Intershop 7 via a special REST API. The API can also be used by external systems or by custom clients allowing them to connect to IS7.

Software Version Information

The content of the present document is valid for the following combinations of software versions:

Glossary

Giving an overview of used terminologies and expressions in reference to the Intershop Contact Center application.

References

• Concept - REST Framework
  Reference to intershop REST framework

• Cookbook - JUnit Tests
  A reference on how to write a JUnit 4 test and how mocking works. At the end of the page "Mocking with Guice" is explained.

Architecture

Overview

An Intershop 7 installation can be divided in editing systems and live cluster. Both are accessable via the Web Adapter. Changes in the edit system are replicated to live system where the real web shops are running. The Web shop technology provides a REST API that provides calls for almost all purchase relevant topics like catalog browsing, cart and checkout functionality, promotion topics and even account management issues.The new Contact Center extension module is developed as an independent application. It can be deployed on a separate web server. The application communicates with Intershop 7 via REST. A Contact Center REST API is deployed to the Intershop 7 server and extends the WebShop REST API by some specific calls like customer search, checkout on behalf of a customer, or generating vouchers. Other external data systems like ERP or recommendation engine can be easily integrated via REST, too. And vice versa the Contact Center REST API can easily be used by external systems.

Assembly, Component Set and Cartridge Structure

The whole extension module for the Contact Center is combined in an own assembly. It contains the Contact Center UI as well as demo data (customers).
The cartridges are only code containers. They cannot be overwritten by customized cartridges containing parts of the standard cartridge.
The following figure outlines the cartridge structure.

Initialization (DBInit)

The server-side initialization is part of the Intershop Commerce Management 7.6.

Application Type and Root Domain

Application type and root domain are defined in the cartridge as_contactcenter.

Application type: intershop.CC

Root domain: root.sites = ContactCenter

Permissions and Roles

Permissions and roles are defined in init_contactcenter.

The following permissions for the Contact Center are defined:

The following roles are defined for now:

Application Architecture

The Contact Center application is based on the Omni-Channel Service Framework which consists of several Ember artifacts. So the framework is like a technology container which can easily be extended and adapted for the customer’s needs. The UI is application specific. It contains several views for the user’s interactions. A Web page can consist of several views and a view can use other views.

The data which are displayed and editable are stored in models. A model is a class that defines the properties and behavior of the data that you present to the user. Anything that the user expects to see if they leave your app and come back later (or if they refresh the page) should be represented by a model. Different views are used by different models that allow the display and change of their data.

There is a program layer which holds the functional structure of the application, the controllers. In Ember.js, controllers allow to decorate models with display logic. In general, the models will have properties that are saved to the server, while controllers will have properties that your app does not need to save to the server. A controller can use several models and a model can be used by several controllers. The methods of the controller prepare the REST calls with manipulated data or changes the model values with data received from the REST calls responses.

The wiring between model, view and controller is defined by so called routes which can be accessed via the URL.

Controllers communicate with the REST API of IS 7 via adapters. These adapters contain the REST calls themselves and execute the call with the parameter values prepared by the controller. The responses are returned to the controllers.

OCST Deployment

The contact center UI server uses a new concept to deliver functionality of the presentation layer. The UI server has no direct database link as the IS 7. The client directly communicates with the REST interface of IS 7.

The contact center UI server has less infrastructure requirements than an IS 7. Depending on who is using the functionality different deployment scenarios are possible.

NFRs:

• Application server is not directly accessible from the internet.
• Indirect access to application server to be support easier maintenance.

Deployment Scenarios

The usage of mod_jk and Web Adapter in one Web server needs to separate these requests by an URL pattern (defined in the httpd.conf). This could decrease the flexibility of URL rewriting.

Development Scenario

The development environment does not need multiple server instances. So everything is deployable at one machine.

The Contact Center UI server is accessible via mod_jk or via the outer tomcat URI. The configuration of the contact center UI server needs the location of the WA-storefront.

Staging Inside Scenario

The Staging Inside Scenario fits for an inhouse usage of the Contact Center. The IT department is responsible to serve IS 7 and Contact Center.

The Contact Center UI server is configured with the name and port of the Load Balancer.

Outside Scenario

This scenario has an independent deployment of IS 7 and Contact Center UI Server. This scenario is important for external call center agencies or departments with different IT.

The gray box is an external system without administrative access. But this environment needs the Contact Center cartridges for Contact Center communication.

Client Technology

The client application has to provide a appealing user interface for an Contact Center Agent. The clients communicate with the application server by using REST calls.

In the following the architecture and the different user interaction scenarios are described.

Web Application Technology

The Contact Center client is not a Intershop-specific cartridge, but a standalone Web application that can be deployed to a simple J2EE app server (e.g., Tomcat). The project f_ocst/app_contactcenter is configured as a Eclipse Web Tools (WTP) project that can be run and debugged directly from the Intershop Studio. It is built as a standalone Gradle project.

The client can be configured via the file /WEB-INF/resources/config/configuration.xml. It contains the necessary settings for the REST APIs the client can use, as well as the payment whitelist settings:

	<bean id="webshop"
        class="com.intershop.ocst.controller.configuration.beans.WebshopConfiguration">
        <property name="restURIBase" value="${WebshopRestURIBase}" />
        <property name="restURI" value="${WebshopRestURI}" />
        <property name="version" value="7.6.0" />
    </bean>
 
    <bean id="contactcenter"
        class="com.intershop.ocst.controller.configuration.beans.OCSTConfiguration">
        <property name="restURIBase" value="${OCSTRestURIBase}" />
        <property name="restURI" value="${OCSTRestURI}" />
        <property name="version" value="1.1.0" />
        <property name="paymentMethods">
            <list>
                <value>BPS_INVOICE</value>
                <value>BPS_CASH_ON_DELIVERY</value>
                <value>BPS_DEBIT_TRANSFER</value>
                <value>ISH_INVOICE</value>
                <value>ISH_CASH_ON_DELIVERY</value>
                <value>ISH_DEBIT_TRANSFER</value>
            </list>
        </property>
    </bean>

The placeholders (e.g., ${WebshopRestURIBase}) are filled by the Gradle process. And on the other hand we have the payment methods which are directly filled. Changing the latter parameter requires a server restart.

Ember.js

The JavaScript framework Ember.js provides its own way to model applications. Therefore, structuring elements like routes, models, controllers, adapters, components and views are introduced (see illustration below).

From a controller view perspective the following initial structure was established. In the final version 1.0.0 Controllers and templates in the view layer may have changed their namings.

Require.JS

The JavaScript framework Require.js allows to have controllers, routes, views etc in separate JavaScript files, which can be loaded on demand and defining dependencies (e.g., jQuery-placeholder.js needs jQuery.js). Therefore, the JavaScript code can be structured and included whereever needed.

• RequireJS is a JavaScript file and module loader.
• It is optimized for in-browser use, but it can be used in other JavaScript environments.

Bootstrap

• Bootstrap is a free collection of tools for creating user interfaces for websites and Web application.
• Bootstrap contains HTML and CSS-based templates (snippets) for text, forms, buttons, navigation and other components.
• Bootstrap also contains optional JavaScript extensions.
• Bootstrap is used for the responsive layout of the Contact Center.

jQuery

jQuery is the most used JavaScript framework in history. It is also on the dependencies-list of the Ember.js framework.

• jQuery is a fast, small and feature-rich JavaScript library.
• It allows HTML document traversal and manipulation, event handling, animation and provides an easy-to-use Ajax function for (a)synchronous server requests.
• Works across a multitude of browsers.

Less

• Less is a CSS pre-processor, meaning that it extends the CSS language, adding features that allow variables, mixins, functions and many other techniques that allow you to make CSS that is more maintainable, themable and extendable.

• Less runs inside Node, in the browser and inside Rhino. There are also many 3^rd party tools that allow to compile files and watch for changes.

Handlebars

Handlebars is a HTML-template engine for JavaScript. It allows deeper structuring of code by defining semantic templates for display, which is usually the HTML code of a website. Using individual helper functions, partials (includes) and ember specific helpers (e.g., render, partial, or view) it allows creating a well defined structure for templates. As part of the Ember distribution it is tidly integrated and well documented.

Configuration

The client application configuration can be found inside the home.jsp file. The attributes are used to make the Ember application configurable for development, production or other environments.

<script type="text/javascript">
        /* declare the application webroot path*/
        var OCSTConfiguration = {
        	webRootURI: 'resources',
        	baseURI: '${ocst.restURIBase}',
        	restURI: '${ocst.restURI}',
        	paymentMethodsWhiteList: ${ocst.paymentMethods},
        	webshopURIBase: '${webshop.restURIBase}',
        	/**
        	 * For 7.4.5 "payments"-compatibility the version can be set to '7.4.5'
        	 * Standard is the '7.5.2' version number.
        	 */
        	version: '7.5.2',  
        	    /**
        	     * Refresh interval for Contact Center Session, when only WebShop calls are made
        	     * n (n > 0) - when WebShop calls are made, at least n milliseconds later a CC refresh call is made 
        	     * n ( n <= 0)  - no refresh (for servers with high session timeout)
        	     */ 
        	sessionRefreshTime: 30000,  // milliseconds
    	    /**
    	     * Enabling the clockService which is required for reoccuring events (e.g., automatic session refresh)
        	 * Can be disabled by setting to false (e.g., testing)  
    	     */ 
        	clockService: true,
        	
        	/**
        	 * Internationalization configuration for jquery.i18n.properties.js
        	 * Check I18nInitializer for additional details 
        	 */
        	i18n: { 
	        	/**
	        	 * Available language property files located under /resources/localizations
	        	 * First language is default language when browser language does not match any other
	        	 * language. 
	        	 * Using ' ' is the default language containing the english translation and points to login.properties
	        	 */
	        	languages: [' ', 'de'],
	        	
	        	/**
	        	 * List of all translation properties files available
                 * located under /contactCenter/localizations
	        	 */
	        	propertyFiles: [
	               'application', 'basket', 'cobrowse', 'customersearch', 'customersearchresult', 'hnavbar', 'index', 'login', 'index', 
                   'orderdetails', 'orders', 'ordersummary', 'promotionhistory', 'promotions', 'quickorder', 'storefinder'
	            ],
	            
	            /**
	             * Relative path where all properties files are located
	             */
	            path: './resources/localizations/'
        	}
        };
    </script> 

Localization

The application comes along with localized templates, controllers, views, etc. Therefore, we need language dependent text snippets in JavaScript and Handlebars (template engine) - which are refered to as localized strings.

These localized strings are stored in standard Java properties files. Nevertheless, these files are readout by a JavaScript framework which allows us to access translations in JavaScript (e.g., controllers, routes,..) as well as in templates. The two ways are presented below.

<!-- Text translation -->
TEMPLATE: <h4>{{i18n "login.dialog.header.title"}}</h4>
--> HTML: <h4>Contact Center</h4>
 
<!-- HTML attributes ("unbound" indicates that a constant is displayed) -->
TEMPLATE: <a {{action "doLogout"}} title="{{i18n "hnavbar.menu.logout.title"}}">...</a>
--> HTML: <a title="Logout">...</a>
<!-- Component attributes translation -->
TEMPLATE: {{input type="text" placeholderTranslation="login.dialog.loginname.placeholder"}}
--> HTML: <input type="text" placeholder="Login name">

In JavaScript you can access the jQuery localization plugin i18n.properties directly.

JAVASCRIPT: console.log($.i18n.prop('login.dialog.errors.missing_login'));
-> CONSOLE: "You missed entering your login name."

Within controllers the initialization of attributes should be made within the initialization method. Doing so the localizations get enough time to load, before they are looked up.

// GOOD
FooController = Ember.Controller.extend({
    ...
    init: function() {
        // setting the the localization to the properties "footerButtons" and "title"
        this.setProperties({
           footerButtons: [
                Button.create({title: $.i18n.prop('application.button.close'), clicked: 'close', dismiss: 'modal'})
           ],
           title: $.i18n.prop('quickorder.modal.paymentmethod.title')
        });
    },
    ...
});
 
// BAD (not working)
FooController = Ember.Controller.extend({
   // FAIL! initializing localizations here fails, since localization are not loaded in that early stage of instantiation.
   footerButtons: [
       Button.create({title: $.i18n.prop('application.button.close'), clicked: 'close', dismiss: 'modal'})
   ],
   title: $.i18n.prop('quickorder.modal.paymentmethod.title')
});

The localization files are simple Java properties files that will be resolved locale-dependent, with the most specific locale tried first (e.g., login_en_US.properties -> login_en.properties -> login.properties):

login.dialog.footer.copyright=Intershop 7 ContactCenter - {0} © Intershop Communications, 2014
login.dialog.loginname.placeholder=Login name
login.dialog.password.placeholder=Password

Security

General

The Contact Center Web application runs within HTTPS which means it is secured through SSL encryption. The OCST REST API supports HTTP as well as HTTPS, but the the communication between the Web application and the REST API will be exclusively HTTPS. All REST calls in the OCST REST API are restricted resources that use a token-based Basic HTTP authentication.

The OCST REST API includes a two-step security check. Firstly, a LoginProvider checks if the user (Contact Center Agent) exists and is able to log in to a organization the Contact Center works for.

In the second step a PermissionProvider checks wether the user has the permission (role) to access the REST calls. The needed permissions are defined in the file as_contactcenter\staticfiles\cartridge\components\resources-acl.properties for the domain TargetOrganization which refers to the organization given by theappropriate header field UserOrganization.

Both security checks require a header field UserOrganization which contains the name of the organization where the user is validated against.

The interactive REST client is a single page JavaScript application. Therefore, the user authentication relevant data will be stored within JavaScript. Thus neither cookies must be used nor sensitive data has to be appended to any REST URL requests.

The Contact Center is an standalone application which supports some IS 7 functionality for the use as an Contact Center Agent. The CCA has the special permission SLD_OPERATE_CONTACTCENTER. This role is able to log in in the Contact Center where some more use cases than in the B2C WebShop are available. The CCA is able to select a customer of an special channel and use the B2C WebShop on behalf of the selected customer. This is possible about the connected REST APIs, one for the customer's B2C Web Shop, the other for some customized Contact Center REST calls, e.g., the creation of promotion codes for special promotions created for the Contact Center in the BO.

Login

The user who wants to log in must exist in the given organization (e.g., PrimeTech) and must be assigned to the role Contact Center Contact Center Agent.

In order to log in to the Contact Center UI, the REST call REST API OCST - Get User Details should be used.

To authenticate the user for the first time:
Either

• Add header fields
  • Authorization ; with Value: String "Basic " +Base64-encoded credentials separated by ':' (login + ":" + password)
  • UserOrganization with value login (plaintext)

or

• Add header fields
  • UserLogin with value login (plaintext)
  • UserPassword with value login (plaintext)
  • UserOrganization with value login (plaintext)

The response of this call will contain an authentication-token which should be used to authenticate the user in all further calls.

For repeated access:

• Add Header fields
  • authentication-token ; value: generated token from the first response header
  • UserOrganization with value login (plaintext) - used for permission check

Each token is only valid for a given time period, which is defined by the maximum inactivity time for the accessed site.

Concept - REST Framework

Third Party Libraries

The OCST uses open source JavaScript and CSS libraries.