Setting Up Access Control : ATG CSC

When ATG Commerce Service Center is installed, it is preconfigured with various access rights, global roles, and access controllers. These elements are used to restrict access to certain pages in the Commerce Service Center.

1. Default Access Control Configuration:

The default access control configuration provided with ATG Commerce Service Center includes a number of access rights, roles, and access controllers. The access controllers are Nucleus components, which are added to your ATG installation when you install ATG Commerce Service Center. The access rights and roles are repository data that you import into your database (from supplied XML files) as a configuration step after you install ATG Commerce Service Center. For more information about installing and configuring ATG Commerce Service Center.


1.1 Access Rights:


The basic security unit is the access right. The access rights for ATG Commerce Service Center are subdivided according to the following classification:

a) Tab Security - Security for the Commerce Service Center tab accessed through the Service Framework
     tabs

b) Panel Security - Security for a panel

c) Element Security - Security for a data field or action element within a panel

ATG Commerce Service Center comes preconfigured with access rights that have been designed based on specific CSR agent activities. A subset of these rights is assigned to each Commerce Service Center role, and you assign the appropriate roles to agents to give them the access rights they need.

Add additional information and descriptions on these preconfigured tables. The following table summarizes the preconfigured Commerce Service Center access rights:


ID                                                   Name

issueCredit                                       commerce-custsvc-issue-credit-privilege
adjustPrice                                       commerce-custsvc-adjust-price-priviege.



1.2 Global Roles:


ATG Commerce Service Center comes preconfigured with four global roles for controlling the access rights granted to CSR agents. The Commerce Service Center roles use template roles to simplify their configuration:

a) csrTicketing - Includes the access rights necessary to use the Ticketing UI

b) csrOrders - Includes the access rights needed to create and modify orders. In addition,
    this role includes csrTicketing as a template role, so all ticketing access rights are included

c) csrProfiles - Includes the access rights needed to create and modify customer profiles.
    In addition, this role includes csrTicketing as a template role, so all ticketing access rights
    are included

d) csrManager - Includes csrOrders (and thus csrTicketing) and csrProfiles as template roles

For a list of all access rights for each role, and a description of the access right
When you create an agent’s profile in the Internal User Profile Repository, you assign the agent a role that corresponds to the tasks the agent is authorized to perform. For example, a typical agent may be able to create and modify orders, but only a manager can override prices and issue credits.


1.3 Creating New Roles:


If you have requirements that none of the existing roles meet, you can create new roles.

To create new roles:

1. Open the BCC > Personalization page.

2. Select Internal Users.

3. Use the Show menu to select Organizations and Roles.

4. Open the Global Roles folder. Identify the location to store the role.

5. Click the Create New icon to create the new role.

6. Enter the name of the new role.

7. Select the Access Rights tab to add existing access rights, or to create new access rights by
    specify Direct Access Rights or incorporating the access rights from existing roles by using
    the Template Role field.

8. Once you are finished, click Create to save your settings.

2. Creating Agent Profiles:

By default, ATG Commerce Service Center is not preconfigured with any agent profiles. As part of setting up ATG Commerce Service Center, you need to:

1. Create a profile in the Internal User Profile Repository for each agent.

2. Assign each profile a global role.

If you want to create a sample account for evaluation purposes, ATG Commerce Service Center provides a file named csrEvalUser.xml. Importing the data from this file creates an account whose username and password are both csr. This account is assigned the csrManager role, which means it has access to all areas and activities in the Commerce Service Center and the Ticketing UI.

Note: This account should be added only to the database that is provided with the ATG platform for evaluation purposes. You should not include it in a production database, as this is a serious security risk.

Configuring Return Shipping Addresses : ATG CSC

To configure the shipping address for returns, perform the following steps:


Create a JSP file that contains your shipping address. 


For example:


<ul class="atg_commerce_csr_simpleList">
<li><strong>Ship return items to:</strong></li>
<li>My Company</li>
<li>Attn:Returns</li>
<li>100 Main Street</li>
<li>My City, My State</li>
<li>My Zip</li>
</ul>


Open the atg/commerce/custsvc/ui/renderers/
ReturnShippingAddressRenderer.properties file and provide the location of the new JSP file and the contextRoot variable.


For example:


# This is the default renderer for the returns line item page, default
# renderers will all have their id property set to "default". This
# property is primarily useful in targeting rules.
id=default


# The JSP that renders the returns line item
url=/panels/order/returns/NewreturnShippingAddress.jsp
contextRoot=/NewDCS-CSR


Save the ReturnShippingAddressRenderer.properties file.

Determining a Customer’s Locale

A customer’s locale determines the language that the customer sees when viewing a site in CRS. This
section describes how a customer’s locale is determined for each request.
Setting a customer’s locale is implemented through a series of includes. To start, an include-prelude
statement in the /WEB-INF/web.xml file specifies that the store.war/includes/prelude.jspf page
fragment should be included for all CRS JSP pages. prelude.jspf, in turn, includes the
store.war/includes/context.jspf page fragment. This fragment contains code for identifying and
setting the customer’s locale and it looks like this:

<%-- Identify and set customer's locale --%>
<dsp:importbean var="requestLocale" bean="/atg/dynamo/servlet/RequestLocale" />
<fmt:setLocale value="${requestLocale.locale}"/>
The context.jspf fragment invokes the /atg/dynamo/servlet/RequestLocale component
included in the Store.EStore.International module. RequestLocale is of class
atg.projects.store.servlet.StoreRequestLocale, which extends the
atg.userprofiling.ProfileRequestLocale class with the following logic that determines a user’s
locale:
· First, RequestLocale determines if a locale parameter is included in the HTTP
request. The locale parameter is embedded in the links associated with the language
picker on the store.war/navigation/gadgets/languages.jsp gadget. When a
customer clicks a language in the language picker, an appropriate locale is sent in
the ensuing HTTP request. (See Rendering the Language Picker in the Multisite
Features chapter for more details on the requests generated by the language picker.)

· If a locale is not present in the HTTP request, RequestLocale looks to see if a
siteId is included in the request. If a siteId is included, RequestLocale uses the
default locale for that site, as defined by the defaultLanguage property in the site’s
configuration.

· If neither a locale nor a siteId parameter is present in the HTTP request,
RequestLocale retrieves the locale from the customer’s profile.

· If a locale is not present in the customer’s profile, RequestLocale retrieves the
locale from the browser’s userPrefLanguage cookie.

· If the userPrefLanguage cookie is not present, RequestLocale uses the browser’s
default locale.

· If the browser does not have a default locale, RequestLocale uses its own default
setting, as specified by the optional defaultRequestLocale property in the
RequestLocale.properties file.

· Finally, if RequestLocale doesn’t have a default setting, it uses the JVM’s locale
default.

Once a locale is determined, RequestLocale sets the locale property in the customer’s profile and
writes a userPrefLanguage cookie to the browser that specifies the customer’s locale.
The context.jspf page fragment also calls the fmt:setLocale tag from the JavaServer Pages
Standard Tag Library (JSTL). This tag sets the locale for any additional fmt tags called for the remainder of
the request, such as the fmt:message tags that are used for displaying localized strings
Note: For more information on JTSL tags, see
http://java.sun.com/products/jsp/jstl/1.1/docs/tlddocs/index.html.

ATG CSC Architecture

ATG Commerce Service Center (CSC) is comprised of customer-facing (or production) and agent-facing clusters. The customer-facing cluster contains the customer store, ATG Commerce, ATG Self Service and other client facing components. The agent-facing cluster contains ATG Knowledge, ATG Commerce Service Center and other agent-facing components.

ATG CSC: Data Collection Overview

As with all reporting, CSC Reporting data collection starts with the firing of a log-worthy event. The EventListener listens for the events, gets the appropriate object and passes it to the LogEntryQueueSink. The EventListener Nucleus component is configured with the property dataListeners=LogEntryQueueSink.

The LogEntryQueueSink property is a DataCollectorQueue type property and ensures the correct timing of writing to the log files. The LogEntryQueueSink component is configured with the property dataListeners=LogEntryGenerator to ensure that message will be passed on to the LogEntryGenerator.

The LogEntryGenerator property is used to generate a LogEntry object. This object is passed to the LogEntryLogger that has been configured with the parameters dataListeners=LogEntryFileLogger. The LogEntryLogger component of the RotationAwareFormattingFileLogger class logs items to the named file, and then rotates the log file based on a schedule and data threshold. It also contains a formatFields property that is used to indicate properties that should be written to the file.

Returns and Exchanges Data Collection Properties

The returns and exchange data collection process starts with the firing of the return/exchange event. The ReturnFormHandler fires the ReturnOrder event. The ReturnEventListener listens to the events.

The ReturnEventListener file is configured as follows:

$class=atg.commerce.reporting.ReturnEventListener
enabled^=/atg/dynamo/service/DWDataCollectionConfig.enabled
dataListeners=ReturnLogEntryQueueSink
returnOrderJMSType=atg.commerce.csr.ReturnOrder
exchangeOrderJMSType=atg.commerce.csr.ExchangeOrder

The ReturnLogEntryQueueSink listens to messages from event listener and queues the log entries to avoid performance bottleneck. Calls made to this component are queued and then passed to the ReturnLogEntryGenerator. The ReturnLogEntryQueue configuration file is configured as follows:

$class=atg.service.datacollection.DataCollectorQueue
dataListeners=ReturnLogEntryGenerator

The LogEntryQueue passes the data to the ReturnLogEntryGenerator that generates the ReturnLogEntry and passes it to the ReturnLogEntryLogger. The ReturnLogEntryGenerator file is configured as follows:

$class=atg.commerce.reporting.ReturnLogEntryGenerator
dataListeners=ReturnFileLogger
enabled^=/atg/dynamo/service/DWDataCollectionConfig.enabled


The ReturnFileLogger component is responsible for writing logs items to the named file, as well as rotating log files based on schedule and data thresholds. The ReturnFileLogger component also has formatFields property that indicates which properties should be written to file. The ReturnFileLoggerLogger configuration file contains the following:

#class
$class=atg.service.datacollection.RotationAwareFormattingFileLogger
# directory and file name of log file
logFileName=csc_return_
# Rotate log files automatically every 1 hour
schedule=every 1 hour
# Or rotate when there are 10,000 records in the file
dataItemThreshold=10000
# The directory to place all the log data files
defaultRoot^=/atg/dynamo/service/DWDataCollectionConfig.defaultRoot
# The centralized Dynamo scheduler
scheduler=/atg/dynamo/service/Scheduler
# Add a timestamp to all the names of the log files
timestampLogFileName=true
# Use this extension after the timestamp
logFileExtension=.data
# Format the time stamp like so (month-day-year_hour-minute-second-
# millisecond)
timestampDateFormat=MM-dd-yyyy_HH-mm-ss-SS
# properties to log (in order)
formatFields=timestampAsDate:MM/dd/yyyy HH:mm:ss,
returnOrder.returnRequestId
enabled^=/atg/dynamo/service/DWDataCollectionConfig.enabled
# Add a Unique ID to all the names of the log files
UIDLogFileName=true
# IdGenerator
idGenerator=/atg/dynamo/service/IdGenerator
# The JMS message type
logRotationMessageType=atg.reporting.ReturnOrder
# The messageSource component to send log rotation message
messageSource=/atg/dynamo/service/LogRotationMessageSource
Returns and exchange log files are written to the /atg/dynamo/service/
DWDataCollectionConfig.defaultRoot directory.

Call Data Collection Properties

CSC can generate calls using the start call function or by using the integrated eStara Click to Call functionality. For information on eStara Click to Call, refer to the Configuring eStara Click to Call chapter.

When a call is initiated, a unique call ID is generated and assigned for each call. The call ID is used when starting and ending call events. The atg.agent.events.CallEvent event extends the atg.agent.events.AgentEvent event by adding callId, startTime and endTime properties. The startTime and endTime properties are recorded to the database as audit logs, while the callId is added to the audit database record.

The /atg/agent/logging/AgentAuditQueue listens for all agent events and passes the control to the AgentAuditLogger and provides an additional AgentFileLogger listener. This listener writes the data item to the file system. The TypedEventDataListener contains the AgentAuditLogger, the AgentFileLogger and the SelfServiceAuditLogger components.

The CallLogEntry and CallLogEntryGenerator classes provide the ability to add additional data to the log processes.

The CallFileLogger logs the data to the file system and creates an entry for the end call event. This logger will not log an entry for the start call event. When an agent ends a call the end call event is fired. Should an agent forget to end the call, when the window is closed or the CallState component is out of scope, the doStopService method will end the call event.

The CallFileLogger is configured with the following:

#class
$class=atg.service.datacollection.RotationAwareFormattingFileLogger
# directory and file name of log file
logFileName=svc_end_call_
# Rotate log files automatically every 1 hour
schedule=every 1 hour
#Or rotate when there are 10,000 records in the file
dataItemThreshold=10000
# The directory to place all the log data files
defaultRoot^=/atg/dynamo/service/DWDataCollectionConfig.defaultRoot
# The centralized Dynamo scheduler
scheduler=/atg/dynamo/service/Scheduler
# Add a timestamp to all the names of the log files
timestampLogFileName=true
# Use this extension after the timestamp
logFileExtension=.data
# Format the time stamp like so (month-day-year_hour-minute-second-
# millisecond)
timestampDateFormat=MM-dd-yyyy_HH-mm-ss-SS
# properties to log (in order)
formatFields=timestampAsDate:MM/dd/yyyy HH:mm:ss, callId,
startTimeAsDate:MM/dd/yyyy HH:mm:ss, endTimeAsDate:MM/dd/yyyy HH:mm:ss,
customerId, agentId
enabled^=/atg/dynamo/service/DWDataCollectionConfig.enabled
# Add a Unique ID to all the names of the log files
UIDLogFileName=true
# IdGenerator
idGenerator=/atg/dynamo/service/IdGenerator
# The JMS message type
logRotationMessageType=atg.reporting.svc.Call
# The messageSource component to send log rotation message
messageSource=/atg/dynamo/service/LogRotationMessageSource

Setting Up ATG Commerce Service Center

The following instructions describe how to set up ATG Commerce Service Center. If you are installing ATG CSC with an existing installation of ATG Commerce, refer to the Configuring ATG Commerce Service Center with ATG Commerce section.

Note: If you have installed ATG Service, you have already performed the first three steps. Continue to Step 4.

1.             Create the ATG Commerce Service Center databases. If you have not already done so during the installation of ATG Service, create both an Agent and a Production Database as outlined in the ATG Service Installation and Configuration Guide.

2.             ATG Commerce Service Center will use a similar schema configuration that you created for the installation of ATG Service. If you have not already run the installation process when setting up ATG Service, run the create-service-allscript in the <ATG9dir>/Service9.4/Service/install directory for your database type. This script runs a number of SQL files for your specific environment. You can use your own database tool to run the various SQL files outlined in the create-service-all script. Refer to the Creating Database Schema section of the ATG Service Installation and Configuration Guidefor additional information.

3.             Ensure that your data sources are configured correctly. Refer to the Creating ATG Service Servers section of the ATG Service Installation and Configuration Guide for additional information on how to direct data sources.

·                     JTDatasource on your customer-facing server – points to your customer-facing server

·                     JTDatasource on your agent-facing server –points to your agent-facing server

·                     JTDatasource_production on your agent-facing server – points to your customer-facing server

4.             Install the ATG Commerce Service Center tables by running the following scripts. Refer to the list in the Required Databases and Users section for the list of specific DDL files.

Script	Run against this schema
<ATG9dir>/CSC9.4/DCS-CSR/sql/db_components/ database-vendor/DCS-CSR_ddl.sql	Production
<ATG9dir>/CSC9.4/DCS-CSR/sql/db_components/ database-vendor/DCS-CSR_ticketing_ddl.sql	Production
<ATG9dir>/CSC9.4/DCS-CSR/sql/db_components/ database-vendor/DCS-CSR_logging_ddl.sql	Agent
<ATG9dir>/CSC9.4/service/sql/db_components/ database-vendor/service_datawarehouse.sql	Data Warehouse

5.             Import the data by going to the <ATG9dir>/home/bin directory and entering the following commands:

startSQLRepository –m DSS –repository
/atg/userprofiling/InternalProfileRepository – import
<ATG9dir>/Publishing/base/install/epub-role-data.xml

6.             Execute the following files to import login and access rights data:

<ATG9dir>/CSC9.4/DCS-CSR/install/importDCSCSR.sh
<ATG9dir>/CSC9.4/DCS-CSR/install/importDCSCSREvalSuperUser.sh

Note: The -s <servername> argument is optional for the importDCSCSR and importDCSCSREvalSuperUser scripts. If the scripts are executed in the agent cluster, and you provide the -s <servername> parameter, the script assumes that the data source settings are setup on the server indicated.

7.             Create the EAR file by running a command similar to the following from <ATG9dir>/bin directory:

runAssembler DCSCSR.ear –m DCS-CSR DCS-CSR.DW Fulfillment

If you have made customizations to the DCS-CSR module and saved it as MyStoreDCS-CSR, add your store customizations to the EAR file after the DCS-CSR module:

runAssembler MyStore.ear –m DCS-CSR MyStoreDCS-CSR DCS-CSR.DW Fulfillment

Note: When starting the ATG Commerce Service Center server, you must include all the modules you use with your external site, plus the DCS-CSR module. The external site’s module must be specified before the DCS-CSR module. The following example installs CSC and CSC reporting:

startDynamoOnJBoss -m DCS-CSR DCS-CSR.DW Fulfillment

8.             Deploy the EAR to the application server. Refer to your web application server documentation for information, as well as information for your web application server in the ATG Installation and Configuration Guide.

9.             Start the server according to the instructions in your application server documentation.

ATG CSC : Adding a New Panel to Commerce Service Center

The Service application maintains a list of valid UI components in atg/svc/ui/util/ServiceUIComponentDataStore. In order to add panels to the CSC UI, it's necessary to do extend that class. As well as being defined in the ServiceUIComponentDataStore, the panels must be added to the Service Repository. This can be accomplished by performing an xml combine with the existing svc_framework.xml file. The following steps provide a working example.

1) Create a new Nucleus Component which extends ServiceUIComponentDataStore
Place the component in your config layer at /atg/svc/ui/util/ServiceUIComponentDataStore.properties.

$class=com.example.MyServiceUIComponentDataStore
$scope=global

2) Create a new Class which extends ServiceUIComponentDataStore
The class will override the initializeService method to add the CSC panel.

package com.example;
public class MyServiceUIComponentDataStore extends ServiceUIComponentDataStore
{
@Override
public void initializeService() {

// Add additional CSC Panels
addServiceUIComponent ( new atg.svc.ui.util.ServiceUIComponent
("myAdditionalPanel1",  CSR_LICENSE, CSR_MODULE_NAME,  PANEL_TYPE) );

super.initializeService();
}
}

3) Update the Service Repository with definitions of the new CSC panel.
The Service application stores Panels, Panel Stacks and all other Framework type objects in a Repository. This is defined in the install/data/svc_framework.xml file. We must extend this repository to add the additional panels that were created in the CSCServiceUIComponentDataStore above.

NOTE: the example panel defintion below points to the shopping cart. The following properties will need to be changed: titleKey, resourceBundle, contentUrl and otherContext.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE gsa-template SYSTEM "dynamosystemresource:/atg/dtds/gsa/gsa_1.0.dtd">

<gsa-template>
<add-item item-descriptor="PanelDefinition" id="myAdditionalPanel1">
 <set-property name="appId" value="workspace"/>
 <set-property name="panelId" value="myAdditionalPanel1"/>
 <set-property name="accessRight" value="AdditionalPanel1"/>
 <set-property name="titleKey" value="cmcShoppingCartP"/>
 <set-property name="resourceBundle"
   value="atg.commerce.csr.FrameworkResources"/>
 <set-property name="contentUrl" value="/panels/order/cart.jsp"/>
 <set-property name="otherContext" value="yourwebapp"/>
 <set-property name="templateIds"
   value="panelTemplate=panelTemplate"/>
 <set-property name="tabHolderYn" value="true"/>
 <set-property name="allowContentToggleYn" value="true"/>
 <set-property name="allowTabbingYn" value="true"/>
</add-item>
</gsa-template>

The new panel can be added to any existing Panel Stack by updating its panelIds property. Similarly, the panels may be added to a new panel stack.

Now that the Repository definition has been extended and the panels added to the required panel stack, the Service database should be reloaded and the application restarted. Be sure to clear out the browser cache, before logging on to CSC. The new panels will then be visible.

ATG CSC : Adding a New Tab to Commerce Servie Center

Adding a new tab to Commerce Service Center is similar to adding a new panel, with a couple of additional steps.

1) Create a new Nucleus Component which extends ServiceUIComponentDataStore
If you have previously created this component, this step is not necessary. Otherwise place the component in your config layer at /atg/svc/ui/util/ServiceUIComponentDataStore.properties.

$class=com.example.MyServiceUIComponentDataStore
$scope=global

2) Create or update a Class which extends ServiceUIComponentDataStore
Either create a new class or update an existing class that will override the initializeService method to add the CSC tabs.

package com.example;
public class MyServiceUIComponentDataStore
extends ServiceUIComponentDataStore
{
@Override
public void initializeService() {

// Add additional CSC Tabs
addServiceUIComponent (
 new atg.svc.ui.util.ServiceUIComponent(
  "myTab",  CSR_LICENSE, CSR_MODULE_NAME,  TAB_TYPE) );

super.initializeService();    
}
}

3) Update the Service Repository with definitions of the new CSC tabs.
As with panels, it's necessary to extend install/data/svc_framework.xml to add the additional tab definitions. In the example below, a new myTab tab definition is being added. It renders a new panel stack called myNewPS, which renders the additional panel added in the adding new panels.

NOTE: The following properties will need to be changed for the tab definition:
tabId
titleKey
resourceBundle
actionId
accessRight
panelStackAssignments - The panel stack assignments, indicating the cell within the page layout where each panel stack is displayed. See the example below.
currentPanelStacks - The list of panel stacks that get rendered when the tab is accessed. See the example below.
panelStackOrder - The list of all panel stacks for the tab in rendering order. This supports the case where rendering dependencies exist between panel stacks that require the panel stacks to be rendered in a specific order. See the example below.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE gsa-template SYSTEM
"dynamosystemresource:/atg/dtds/gsa/gsa_1.0.dtd">

<!--
The new myNewTab tab definition
-->
<add-item item-descriptor="TabDefinition" id="myNewTab">
<set-property name="appId" value="workspace"/>
<set-property name="tabId" value="myNewTab"/>
<set-property name="titleKey" value="myNewTab"/>
<set-property name="resourceBundle"
value="atg.commerce.csr.FrameworkResources"/>
<set-property name="actionId" value="myNewTab"/>
<set-property name="accessRight" value="myNewTab"/>
<set-property name="panelStackAssignments"
value="myNewPS=contentColumn,globalPanels=globalCell,helpfulPanels=sidebarColumn/>
<set-property name="currentPanelStacks"
value="myNewPS=contentColumn,cmcHelpfulPanels=sidebarColumn,globalPanels=globalCell"/>
<set-property name="panelStackOrder"
value="cmcHelpfulPanels,helpfulPanels,myNewPS"/>
<set-property name="templateIds"
value="contentHeader=contentHeaderTemplate"/>
</add-item>

<!--
The panel stack that gets rendered initially when the tab
is loaded. This is done by setting the currentPanelStacks
property of the tab definition.
-->
<add-item item-descriptor="PanelStackDefinition"
id="myNewPS">
<set-property name="appId" value="workspace"/>
<set-property name="panelStackId" value="myNewPS"/>
<set-property name="errorPanelId" value="errorPanel"/>
<set-property name="header" value="contentHeader"/>
<set-property name="titleKey" value="myNewPS"/>
<set-property name="resourceBundle"
value="atg.commerce.csr.FrameworkResources"/>
<set-property name="panelIds"
value="errorPanel,myAdditionalPanel1"/>
</add-item>

<!--
Update the existing framework to be aware of the new tab.
-->
<update-item item-descriptor="FrameworkDefinition"
id="WsAgentFramework">
<set-property name="tabIds" value="myNewTab"
remove="true"/>
</update-item>

<update-item item-descriptor="FrameworkDefinition"
id="WsAgentFramework">
<set-property name="tabIds" value="myNewTab"
add="true"/>
</update-item>

<gsa-template>

4) Create a Javascript function to render the new tab
The actionId property of the tab definition points to a Javascript function that gets invoked to render the new tab when a user clicks on it. The Service framework already has a function to change to an existing tab, so we just call that. Create a function like the one below:

function myNewTab(){
atgChangeTab(atg.service.framework.changeTab('myNewTab'),
           null,null,null);
}

Now that the all the necessary updates have been made, the Service database should be reloaded and the application restarted.. Be sure to clear out the browser cache, before logging on to CSC. When a user clicks on the new tab, the new panel stack is rendered and displays the panel.

ATG CSC UI Customization

UI Modification

Mostly customers using ATG CSC will want to make at least minor UI customizations. This could include providing information to CSRs about alternate payment types (PayPal, BillMeLater, Gift Cards), displaying customer loyalty program status, or more involved changes to support non-standard actions or flows.

Commerce Assist UI

When modifying the UI of the old Commerce Assist product, you basically ended up loading the DCS-CSR WAR into your own project (SVN/Eclipse), editing it’s JSPs directly, and deploying it out at the ATG install as part of your build process. While a little hacky, it was a very straight forward and simple process. Most of the JSPs were simple and used a small number of basic included files to support common fragments. Looking at a page in the Commerce Assist tool, and then tracking down which JSP you’d need to modify to change the page was very easy. The whole UI was driving using a single WAR filled with straightforward JSP files. With an Eclipse builder setup to call an ANT task that copies out the JSPs, you can actually see your UI changes in the Commerce Assist application in real time; no building, no bouncing. Simple.

ATG CSC UI

The new CSC tool’s UI is a much more complicated beast. The user interface is built dynamically using a mis-mash of JSPs and JSP fragments coming from two completely different WARs. The overall Service interface mostly comes from the agent.war, which is part of the Service module, where as commerce specific elements (such as order presentation and manipulation, catalog browsing, etc…) are pulled from the CSC’s DCS-CSR.war. There are many more JSP fragments and includes used, and the organization of the file is much more complex and confusing than the old Commerce Assist.

UI Framework Repository Data

The way the interface is built, how tabs and panels are presented, is managed via repository items in the database. These UI Framework items are the reason that you have to run a CA instance within CSC. This CA instance is used to deploy out the data used to build the UI. Until you setup CA and run a Full Deployment, you can’t even hit the CSC at all, since none of this data is available. Perhaps there is a good reason that these UI data elements need to be versioned and deployed from a workflow, independent of code/JSP development that makes sense in ATG Service, but within the context of CSC I doesn’t make any sense to me.

UI Components

Presumably in order to make UI customization easier, the JSPs (both from agent.war and DCS-CSR.war) include many fragments, and many of these fragments aren’t loaded via simple includes, but instead have includes referencing properties on Nucleus components. There are a number of undocumented components which each point to a JSP URI and a context root. For instance, a JSP representing a panel within the UI might include three sub-fragments by referencing three different ATG components, and doing each include based on properties of that component.

The premise is that instead of having to load the ATG WAR(s) into your project, and modify JSP files within the WARs, you can create a new custom WAR (myapp-csc.war), create new JSPs in that WAR for whatever overrides you need to make, and using the config layer override the URL and context root on the appropriate UI component. Then the parent JSP will include your custom JSP fragment from your WAR instead of the default JSP fragment.

This sounds great! Unfortunately it all breaks down about 5 minutes after you start actually looking at the JSPs.

The first issue is that many of the fragments you’d like to modify use a JSP (not DSP) include of a top.jspf file. You can’t just copy and paste the original JSP to your new JSP and modify it in place, because that include will fail and break most of the original functionality of the fragment. Because it’s a JSP include you can’t point it back at the original WAR context root. You have to copy the top.jspf into your war. However, agent.war and DCS-CSR.war have two different top.jspf files (in the same relative path), for instance one loads in the dsp taglib with a prefix of “dsp” while the other uses a prefix of “dspel” as well as many other differences. So assuming you want to override JSPs from both WARs, which is pretty likely, you have to copy in both, rename them, and reference the correct one for each of your custom JSPs. As far as I could tell, none of this was documented. Then you go ahead and setup your config layer overrides, build, and deploy.

The second issue is that there’s a great deal of logic and markup that is NOT in JSP fragments loaded in this way. As soon as you hit this scenario (which you will), you’re back to loading in the ATG WARs into your project, modifying the JSPs directly, and building out your customized versions of the WARs to the ATG install for assembly into the EAR. Only now you’re doing it on two WARs, not one.

As soon as you hit the second issue, you have to question the logic of using the configuration system at all, since it just adds more complexity, and you’re probably better off just working with the ATG WARs you have in your project.

Extensive markup and logic is hidden in tags

Then you’ll find some section of the UI that you need to change, only you can’t find the JSP that’s creating the markup. This is because there are JSP tags which include hundreds of lines of HTML output and JSP logic (DCS-CSR.war/WEb-INF/tags/displayOrderSummary.tag is a great example of this). So now you’re modifying tags as well as JSPs.

AJAX and DOJO

Another element that increases the complexity is that much of the interface is now AJAX driven, so pages are built and rebuilt via Javascript and AJAX calls, not just straight forward JSP. Figuring out how to make modifications to an AJAX driven UI is complex enough when its your own application and code, it’s MUCH harder when it’s two (two WARs) black boxes of DOJO magic with no documentation.

To summarize

In order to make relatively minor modifications to the CSC’s UI, you have to deal with:

1. UI Framework Data in the DB and deployed via CA
2. A custom WAR with JSP overrides and config files to override UI component properties
3. JSPs in DCS-CSR.war, which you’ve had to add to your project and edit directly
4. JSPs in agent.war, which you’ve had to add to your project and edit directly
5. Tags in both wars
6. Undocumented DOJO AJAX logic

It’s a real pain. I’m sure many of the changes were well intentioned, but in my experience when the rubber meets the road the new UI system makes customization and debugging much more difficult.

ATG CSC Search Issues

For some unknown reason ATG has replaced the standard Repository based search used for looking up profiles and orders with ATG Search engine based indexing and lookups. First off, I’ve never had any issues with the old Repository based search. It always seemed fast and worked fine. So I’m not sure why the change was warranted.

Search Issue 1: Supported Environments and Configuration

ATG Search is a 3rd party product ATG acquired so it’s not very “ATG-esque”. It’s also based on native binaries, which means it doesn’t run on Mac OS X, which myself and many others use for development. Configuring and tuning it is a real pain, and in my experience with hosting ATG Search using sites, the binary Search engines will occasionally die or have port conflicts, or otherwise foul up the works. The ATG Search used within CSC to index and provide searching on Profiles and Orders is sort of a sub-Search system. It’s not exactly full blown ATG Search, but it uses the same binaries, configs, and needs you to run Search patches, etc… In fixing a problem, which as far as I can tell didn’t exist, the new ATG CSC 9.1 has dramatically increased it’s install and runtime complexity by requiring ATG Search binary engines to be running.

Search Issue 2: Bulk Indexing Means Downtime

Another issue is if you are upgrading an existing environment, you have to run Bulk indexing on all of your existing Profiles and Orders in your CORE schema during the cut-over. What this means is that after you cut over to the new 9.1 site, using CSC 9.1 your CSR agents will be UNABLE TO HELP CUSTOMERS until the bulk indexing is completed. I’ve seen bulk indexing take ~6 hours per million items. Running profile and order bulk indexing at the same time does work, but also slows down the process a bit. So if you have 2 million orders and 2 million profiles, expect 12-18 hours of CSC downtime while the bulk indexing completes.

Search Issue 3: Incremental Indexing Falls Behind Production Activity

Newly created or updated Order and Profiles make their way into the CSC’s Search indexes by way of incremental indexing jobs, which run every 5 seconds. In testing, this works great. However in production it seems like it’s very easy to have the incoming item index events exceed the incremental indexing rate of processing. By which I mean the incremental indexing queue (SRCH_UPDATE_QUEUE) grows and grows, and your CSC Profile and Order indexes fall further and further behind your live data. Since most CSR calls are about orders placed in the last 24 hours, this becomes a serious problem very quickly as the CSR reps are unable to lookup orders or profiles created in the last X hours, where X continues to grow each day.

Part of this is due to badly planned default configurations, but part of it also seems intrinsic to the product. I am testing some post-patch 2 Search hotfixes, and we’ll see if they help or not. Another complaint I have is that no one told us about the hotfixes until after we’d gone live, and have this issue as a critical problem in our production environment. So if you are going live to CSC 9.1, make sure that ATG gives you any and all hotfixes they may have for CSC and Search BEFORE you go live.

Search Issue 4: Searching is More Limited

Because you can now only search on indexed properties your search options are more limited. For instance you can’t search for all orders in a date range (i.e. orders placed in the last 1 hour or 1 day).

Search Summary

Overall CSC Search is now more complex, harder to upgrade to, more limited, and has some significant production issues. Not a fan.