atg commerce service center installation and configuration … · 2013. 7. 25. · service center...
TRANSCRIPT
Service Center
Version 9.4
Installation and Configuration Guide
Oracle ATG
One Main Street
Cambridge, MA 02142
USA
ATG Commerce Service Center Installation and Configuration Guide
Product version: 9.4
Release date: 10-31-11
Document identifier: CSCInstallationAndProgrammingGuide1307251603
Copyright © 1997, 2011 Oracle and/or its affiliates. All rights reserved.
This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are
protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy,
reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any
means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please
report them to us in writing. If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of
the U.S. Government, the following notice is applicable:
U.S. GOVERNMENT RIGHTS
Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial
computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific
supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and
license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the
additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle America, Inc., 500 Oracle
Parkway, Redwood City, CA 94065.
This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended
for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or
hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures
to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in
dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are
trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or
registered trademarks of Advanced Micro Devices. UNIX is a registered trademark licensed through X/Open Company, Ltd.
This software or hardware and documentation may provide access to or information on content, products, and services from third parties.
Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party
content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to
your access to or use of third-party content, products, or services.
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/us/
corporate/accessibility/index.html.
Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/support/
contact.html or visit http://www.oracle.com/accessibility/support.html if you are hearing impaired.
ATG Commerce Service Center Installation and Configuration Guide iii
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Documentation Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Browser and Environment Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. ATG Commerce Service Center Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
ATG Customer-Facing Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Agent-Facing Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3. Installing and Configuring ATG Commerce Service Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Prerequisites for ATG Commerce Service Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Database and Schema Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Required Databases and Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Configuring ATG CSC with CIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Installing ATG Commerce Service Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Setting Up ATG Commerce Service Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Configuring ATG Commerce Service Center with ATG Commerce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Installing the Production Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Installing the Agent Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Configuring the JTDataSource Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Importing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Configuring Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Configuring IDGenerator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Configuring Lock Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
ServerLockManager on the Customer-Facing Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
ClientLockManagers on the Agent-Facing Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Configuring Order and Profile Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Order and Profile Search Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Configuring Servers for Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Configuring Search Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Installing Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Enabling Report Data Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Accessing ATG Commerce Service Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4. Configuring eStara Click to Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
eStara Click to Call Integration Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Initiating a Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Using a CTI System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Specifying Links and Pop Ups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Automatic Initialization of the Agent’s Working Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
eStara Click to Call Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Configuring the eStara Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Adding an Agent to CSC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Adding Agent Phone Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Configuring Customer-Facing Store Web Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Configuring Automatic Page Instrumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Configuring a Static Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Disabling the Orphaned Session Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Creating Store-Facing eStara Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Using the clickToConnectSave() Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
ATGeStaraCallToken . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Creating Store-Facing Static Click to Call Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
iv ATG Commerce Service Center Installation and Configuration Guide
Creating a Click to Call Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Creating a Click to Call Pop Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Creating a Customized Link or Pop Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Using eStara WinCare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Integrating with eStara WinCare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Integrating without eStara WinCare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Manual CTI Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Configuring CSC Authentication with WinCare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Enabling CSC Auto-Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Disabling CSC Auto-Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Configuring CSC Landing Page Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Default Landing Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Customizing Landing Page Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
5. Configuring ATG Commerce Service Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Configuring Returnable Order States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Working with Exchange Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Configuring Return Shipping Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Setting up Return Reason Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Configuring Return Reason Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Setting up Returned Item Dispositions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Creating Returned Item Dispositions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Configuring Oracle for Catalog Searching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Setting up Scheduled Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Enabling and Disabling Scheduled Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Configuring Price Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Using Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Configuring Scenario Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
CSC Reporting Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Data Collection Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Loader Pipeline Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
6. Setting Up Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Default Access Control Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Access Rights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Global Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Creating New Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Creating Agent Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
7. Customizing ATG Commerce Service Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Using the CSRConfigurator Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Customizing E-Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Configuring E-mail Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
New Password Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Configuring Order Confirmation E-Mails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Configuring E-Mail Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Customizing Scheduled Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Displaying Scheduling Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Scheduled Order Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Scheduled Orders Pipeline Additions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Modifying Submitted Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Cloning Pipelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Cloning Core Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Extending Core Commerce Objects for Cloning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Handling and Fulfillment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Fulfillment Notification for Order Modifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
ATG Commerce Service Center Installation and Configuration Guide v
CSC Pricing Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Loading Orders and Pricing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Return Value API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Submitted Orders and Clone Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Price Lists and Pricing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Automatic Removal of Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Promotions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
API for Determining the Correct PricingModelHolder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Scheduled Order Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Manual Pricing Adjustments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Configuring Catalog and Price Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Using the Current Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Using the Current Price List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Quick Access Catalogs and Price Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Defining the Default Custom Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Defining the Default Price List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Setting the Pricing Locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Enabling Custom Catalogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Customizing Shipping and Payment Group Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Shipping and Payment Group Configuration Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Default Shipping Group Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Default Payment Group Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Customizing Refund Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Configuring Ticket Disposition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
CSC Environment Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Configuring Audit Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Adding a New Agent Audit Log Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Disabling Audit Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Viewing Audit Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Configuring CSC Specific Ticket Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Using Window Scoped Failover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Adding Additional Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Extending ATG Commerce Service Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
CSRShippingGroupFormHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
CSRPaymentGroupFormHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Modifying Keyboard Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Defining Global Keyboard Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Configuring Pages with Nucleus Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Customization Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Simple Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Targeting Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Creating a ProductSkuRenderer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Customization Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Customizing the Order Summary Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Adding a Custom Panel in ATG Service Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Customer Management Panel Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Adding a New Panel to Commerce Service Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Adding a Custom Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Modifying a Tab Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Troubleshooting Tab Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Customizing Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Location of Configuration Property File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Customizing Grids and Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
vi ATG Commerce Service Center Installation and Configuration Guide
Customizable Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Customizing Table Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Customizing Grid Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Customizing Column Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Customizing Page Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Customizing Column Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Working with Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Changing the Item Detail (Hover) Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
A. ATG Commerce Service Center Database Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
ATG Commerce Service Center Core Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
ATG Commerce Service Center Logging Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
ATG Commerce Service Center Ticketing Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
B. CSC Access Rights Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
C. CIM Configuration Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Product Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Available Added Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Server Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Add On Modifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Data Source Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
JTDataSource for Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
JTDataSource for Production . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
CIM File Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Production Server File Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Agent Server File Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
1 Introduction 1
1 Introduction
ATG Commerce Service Center (CSC) is a customizable and deployable customer service application that enables
an agent to perform the following tasks for an ATG Commerce site:
• Create and manage customer profiles
• Create and manage orders
• Issue refunds and exchanges
• Process returned items
• Research customer activity
For information about ATG Commerce, see the ATG Commerce Guide to Setting Up a Store and the ATG Commerce
Programming Guide.
Audience
This manual is intended for Systems, Site Administrators and Programmers responsible for installing, configuring
and customizing ATG Commerce Service Center.
Documentation Conventions
The following conventions are used in this manual:
• Installation Directory
<ATG9dir> — The installation directory for ATG 9.4. For example, the default location for installations is /
ATG/ATG9.4.
• Menu Navigation
The “ > “ (greater than) symbol indicates menu choices. For example, File > Save means you should select the
Save option on the File menu.
2 1 Introduction
Related Documents
The following ATG documentation provides additional reference information:
Document Description
ATG Commerce Service Center User Guide Describes ATG Commerce Service Center concepts and tasks
for agents and end users.
ATG API Reference for Commerce Service
Center
JavaDoc descriptions of ATG Commerce Service Center.
ATG Service Installation and Configuration
Guide
Describes ATG Service concepts and tasks for application
administrators, such as installing ATG Service applications,
configuring ATG Service to work in various combinations
and configuring ATG Search.
ATG Installation and Configuration Guide Describes how to install and configure ATG applications
running on different web applications.
ATG Personalization Programming Guide Describes programming tasks for the ATG Personalization
and Scenarios modules. Includes information on setting up
profile repositories, creating targeting rules and services,
configuring scenario servers, and adding custom scenario
events and actions.
ATG Personalization Guide for Business Users Designed to help business users understand and work with
the ATG Personalization and Scenarios modules. Describes
how to use the ATG Control Center to perform typical
tasks such as segmenting site visitors, defining rules for
personalizing site content, and using scenarios to create
promotional campaigns.
ATG Commerce Guide to Setting Up a Store Describes how to use ATG Business Commerce and ATG
Consumer Commerce to create an online store. Intended for
business users and page developers.
ATG Commerce Programming Guide Describes how to install and customize ATG Consumer
Commerce and ATG Business Commerce. Intended for
programmers and site administrators.
ATG Business Control Center User’s Guide Describes how to use the ATG Business Control Center’s
Web interface to manage user profiles and organizations;
create and assign roles; segment site visitors; and define
rules for personalizing site content. Also includes setup and
configuration information. Intended for all audiences.
1 Introduction 3
Document Description
ATG Repository Guide Describes the ATG Repository API, the heart of ATG’s
Data Anywhere Architecture. Presents programming
concepts for advanced users, including SQL repositories,
LDAP repositories, secured repositories, and composite
repositories. Includes examples and reference information
to help programmers develop applications using the
Repository API.
Before You Begin
This section provides a high-level description of the tasks you need to perform before running ATG CSC:
1. Ensure that Java 1.5.0_16 JDK is installed.
2. Install a supported application server. Consult the ATG Installation and Configuration Guidefor your application
server.
3. Install ATG 9.4.
4. Install and configure ATG 9.4 Commerce.
5. Install and configure ATG Service 9.4.
6. Install a supported Database.
Browser and Environment Requirements
Information about the supported browsers, environments, and configurations is published as a Knowledge Base
article through the My Oracle Support Web site (https://support.oracle.com). To locate the article, search for
“ATG Commerce Service Center Supported Environments” on the Knowledge tab.
Users should enable cookies and scripting in the browser they use to access ATG Service.
4 1 Introduction
2 ATG Commerce Service Center Architecture 5
2 ATG Commerce Service Center
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.
6 2 ATG Commerce Service Center Architecture
ATG Customer-Facing Server Configuration
Customer-facing servers, which provide product catalog information and commerce repositories, employ
several data source components. In this configuration, the JTDataSource component is used for all repositories
other than the product catalog.
ATG Customer-Facing Server Configuration
This information will changed if the JBoss modifications take place:
Note: The product catalog uses the ProductCatalogSwitchingDataSource, which references the
ProductCatalogFakeXADataSourceA and ProductCatalogFakeXADataSourceB components that access
the catalog data.
Agent-Facing Server Configuration
With agent-facing server configurations, the JTDataSource references its own schema rather than the
one used by the customer facing server. In addition to the JTDataSource agent-facing servers use a
JTDataSource_production file. This JTDataSource_productiondata source references all operational data,
which includes profiles, orders, tickets, and inventory data.
The catalog may still continue to uses the ProductCatalogSwitchingDataSource component.
2 ATG Commerce Service Center Architecture 7
ATG Agent-Facing Server Configuration
For additional information on ATG Service architecture, refer to the ATG Service Installation and Configuration
Guide. For additional information on ATG Commerce architecture, refer to the ATG Commerce Programming
Guide.
Note: The ATG Commerce B2B module is not support on ATG Commerce Service Center, and will not function.
8 2 ATG Commerce Service Center Architecture
3 Installing and Configuring ATG Commerce Service Center 9
3 Installing and Configuring ATG
Commerce Service Center
This section discusses the installation of ATG Commerce Service Center (CSC).
Prerequisites for ATG Commerce Service Center
Before you proceed, you must have the following installed or configured:
• Java JDK 1.5.0_16. Ensure that the JAVA_HOME and JAVA_HOME/bin variables are set in your path correctly
• A supported application server, such as JBoss or WebLogic. Consult the ATG Installation and Configuration
Guide for your application server
• A supported database, such as DB2 or Oracle. Create two database users for your database to use, for example
admin and svcagent users.
• ATG 9.4 which includes ATG Adaptive Scenario Engine 9.4, Dynamo Application Framework, ATG
Personalization Server, ATG Scenario Server, and the ATG Business Control Center
• ATG Commerce 9.4
• ATG Service 9.4, specifically for ATG Service Center
Database and Schema Requirements
The following databases and schemas are used in ATG Commerce Service Center. For additional information on
configuration and creation of schemas, refer to the ATG Service Installation and Configuration Guide.
Required Databases and Users
ATG Commerce Service Center requires two different database user accounts for database configuration. Create
the following accounts before configuring the database
10 3 Installing and Configuring ATG Commerce Service Center
Database Schema Contents
svcagent
(Agent)
Versioned repository tables. Referred to in this document as the agent schema.
This schema is accessed from the agent-facing servers.
svcadmin
(Production)
Unversioned repository tables. Referred to in this document as the production
schema. This schema is accessed from the customer-facing servers.
Databases can be configured with the tables on separate machines, separate table spaces or partitions, or in
other configurations.
The following table outlines the SQL files used, the product that the file references, and the schema to which the
file should be pointed:
SQL Product Schema
DCS_ddl.sql ATG Commerce Production
DCS-CSR_ddl.sql ATG CSC Production
DCS-CSR_logging_ddl.sql ATG CSC Agent
DCS-CSR_ticketing_ddl.sql ATG CSC Production
service_agent.sql ATG Service Agent
service_self_service.sql
(optional – required if running Knowledge)
ATG Service Production
service_shared.sql ATG Service Production
service_datawarehouse.sql ATG Reporting Data warehouse
Configuring ATG CSC with CIM
ATG’s Configuration and Installation Manager (CIM) simplifies ATG product configuration by providing the steps
that perform the configuration of the required database tables and necessary CSC modules. This ensures that all
necessary steps are completed and are performed in the correct order. Use CIM to get your installation running
quickly; however, additional configuration on your installation may be necessary.
Note: If you are using CIM to install CSC to an existing ATG application, such as ATG Commerce, do not use CIM
for the installation, as it will reinitialize and configure your ATG application settings. Refer to the instructions for
installing CSC as outlined in the Installing ATG Commerce Service Center (page 11) section.
CIM handles the following configuration steps:
• Creates data sources according to the database connection information you supplied, including those needed
for the ACI data warehouse. and Search
3 Installing and Configuring ATG Commerce Service Center 11
• Creates database tables and imports initial data
• Creates and configures ATG servers, including a lock manager and a required loader servers
• Assembles your application EAR files for each ATG server, including modules for the Agent, Production and
Data Warehouse load servers, as well as DCS-CSR and Fulfillment modules for Agents
• Deploys EAR files to your application server and allows you to start up the agent-facing, customer-facing and
load servers.
• Allows you to add custom modules
See Appendix C, CIM Configuration Components (page 175) for a full listing of the database scripts and
configuration files CIM uses. Refer to the CIM script help and the ATG Installation and Configuration Guide for
additional information on CIM.
To configure CSC using CIM, do the following:
1. Install your application server.
2. Install your applications and the appropriate license files.
3. To start CIM, go to <ATG9dir>/home/bin and type:
cim
4. Select the products you want to configure.
5. Select add-ons, including Search.
6. Continue through CIM according to the prompts. Type H at any prompt for additional information.
Note that CIM does not configure the following:
• Standalone Search engines
• Your Content Administration topography. See the Setting Up an Asset Management Server chapter of the ATG
Content Administration Programming Guide.
• Your Commerce store and IndexingOutputConfig component. See the ATG Commerce Search Guide. CIM
does handle some configuration options, such as whether you plan to index by product or by SKU, but
additional configuration is required.
• Automatic startup for the ProductCatalogOutputConfig components on either production or staging
servers. You must manually configure these components to start automatically.
• Search project, indexing rules, and customizations. See the ATG Search Administration Guide.
Installing ATG Commerce Service Center
Note: If you have run the CIM script, you may have performed these steps. Additionally, if you are setting up a
new environment, you may have already performed these steps when installing ATG Service. Follow these steps
if you are adding to an existing installation:
1. Ensure that you have met all the requirements listed in the Prerequisites for ATG Commerce Service
Center (page 9) section.
12 3 Installing and Configuring ATG Commerce Service Center
2. Download one of the following distribution files from the Oracle website (www.oracle.com):
• Windows: ATG-Service9.4.exe
• UNIX: ATG-Service9.4.jar
3. Unpack and/or run the setup program, which guides you through the process for installing ATG Service
products, including ATG Commerce Service Center. For information on installing and configuring ATG Service,
refer to the Installing ATG Service Applications section in the ATG Service Installation and Configuration Guide.
4. Run the appropriate scripts to create database tables and import repository data, as described below.
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 Guide for 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 (page 9) 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
3 Installing and Configuring ATG Commerce Service Center 13
Script Run against this schema
<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.
Configuring ATG Commerce Service Center with ATG
Commerce
The following information describes the steps necessary to install ATG Commerce Service Center in an existing
ATG Commerce environment.
14 3 Installing and Configuring ATG Commerce Service Center
Installing the Production Schema
If you have an existing installation of ATG Commerce, or of the ATG platform/DCS tables installed on your
production schema, the following SQL files are the only files that should be installed on the production schema.
These files are located in the following directories:
• <ATG9dir>/CSC9.4/DCS-CSR/sql/install/
database-vendor/DCS-CSR_all.sql
• <ATG9dir>/Service9.4/Service/install/scripts/
database-vendor/create-service-all.bat|sh
• If you are adding ATG Reporting, you should also add the <ATG9dir>/Service9.4/Service/install/
scripts/
database-vendor/create-service-datawarehouse-all.sql file in the same schema where your data
warehouse tables are installed. Refer to the ATG Customer Intelligence Data Warehouse Guide for information on
Commerce and CSC reports.
Installing the Agent Schema
Create a new agent schema and add the following SQL files. For information on creating a new agent schema,
refer to the Creating Database Schemas in the ATG Service Installation and Configuration Guide.
• <ATG9dir>/Service9.4/Service/install/scripts/
database-vendor/service_agent_all.sql
• <ATG9dir>/CSC9.4/DCS-CSR/sql/db_components/
database-vendor/DCS-CSR_logging_ddl.sql
Configuring the JTDataSource Files
The JTDataSource file on your agent-facing server should point to the agent schema and the
JTDataSource_production file should point to the production schema. Refer to the Configuring the svcagent
(Agent) Server section of the ATG Service Installation and Configuration Guide for information on configuring the
JTDataSource files.
Importing Data
Once you have created the JTDataSource files, load the initial configuration data into the repositories.
The import data scripts are located in <ATG9dir>/Service9.4/Service/install/
scripts/import-scriptsdirectory. Import Service-specific data by running the import script import-
service-all. This script assumes that two server configurations have been setup, one for agent-facing and
one for customer-facing, and loads both the agent and production data. There are two flags available when
running this import script.
1. Import the data onto the agent-facing server by running the following:
import-service-all -a agent-facing-server-name
2. Import data onto the customer-facing server by running the following:
3 Installing and Configuring ATG Commerce Service Center 15
import-service-all -p customer-facing-server-name
Configuring Repositories
The ATG Commerce Service Center database tables are used by several repositories. Depending on your needs,
you may need to change the configuration of these repositories, such as their data sources. For information on
configuring repositories, refer to the ATG Repository Guide.
The following repositories are shared between your customer-facing server and ATG Commerce Service Center,
in addition to the repositories shared with ATG Service:
• /atg/commerce/catalog/ProductCatalog
• /atg/commerce/claimable/ClaimableRepository
• /atg/commerce/custsvc/CsrRepository
• /atg/commerce/gifts/Giftlists
• /atg/commerce/inventory/InventoryRepository
• /atg/commerce/order/OrderRepository
• /atg/commerce/pricing/priceLists/PriceLists
• /atg/userprofiling/ProfileAdapterRepository
All repositories are configured to use the /atg/dynamo/service/jdbc/JTDataSource_production
DataSource, which should reference the production schema, as outlined in the ATG Service Installation and
Configuration Guide.
For each new repository, the following properties are set by default. If you create new repositories, you should
ensure that these properties are configured:
Property Suggested Value
dataSource /atg/dynamo/service/jdbc/JTDataSource_production
idGenerator /atg/dynamo/service/IdGenerator_production
lockManager /atg/dynamo/service/ClientLockManager_production
eventServer /atg/dynamo/server/SQLRepositoryEventServer_production
subscriberRepository /atg/dynamo/service/jdbc/SQLRepository_production
Configuring IDGenerator
Ensure that all repositories that are used in both the customer-facing and agent-facing servers share the same
IDGenerator component.
16 3 Installing and Configuring ATG Commerce Service Center
By default, any repository defined in the customer facing cluster should use the /atg/dynamo/service/
IDGenerator_production IDGenerator component on the agent-facing server.
Configuring Lock Management
Lock servers synchronize caches among ATG servers to maintain data integrity, even if an item is modified
at the same time by different servers. Configure the ClientLockManager.properties and the
ServerLockManager.properties files to ensure all servers are using the correct ports. For additional
information on ClientLockManager and ServerLockManager properties, refer to the SQL Repository Caching
section in the ATG Repository Guide.
For each SQL repository that contains any item descriptors with cache-mode=“locked”, you must set the
lockManager property of the Repository component to refer to a ClientLockManager. ATG comes configured
with a default client lock manager located at LockManager=/atg/dynamo/service/
ClientLockManager.
By default, the ClientLockManager component has its useLockServer property set to false, which disables
the lock server. To use locked mode repository caching, this property must be set to true. For example:
$class=atg.service.lockmanager.ClientLockManagerlockServerAddress=tartini,corellilockServerPort=9010,9010useLockServer=true
ServerLockManager on the Customer-Facing Server
The customer-facing server cluster should define a primary ServerLockManager instance. Additionally, there
should be a defined ClientLockManager, which points to the primary ServerLockManager.
You can configure backup ServerLockManager instances for redundancy if needed. The following diagram
shows a typical customer-facing configuration:
Customer-Facing Cluster Lock Management
ClientLockManagers on the Agent-Facing Server
Agent-facing servers must use the customer-facing server lock manager for any shared repositories, and
individually scheduled services.
The agent-facing clusters must define a ClientLockManager_production, which points to the
ServerLockManager used by the customer-facing server. The following diagram displays both the customer-
facing server and the agent-facing server configuration.
3 Installing and Configuring ATG Commerce Service Center 17
Agent- Facing Cluster and Customer-Facing Server Lock Management
Configuring Order and Profile Search
CSC uses an enhanced search method for Orders and Customer Profile searches that provide search scalability
and near-real time indexing of profile and order changes. This search process is embedded, and does not require
the installation and set up of a Search Administration server as it is configured and administered using the
Nucleus Admin UI.This search process is not used for ticket or product searches.
Note: To run profile and order searches you must add the DPS.Search.Index and DCS.Search.Order.Index
modules to your EAR file on each customer-facing and management server. DPS.Search.Index is used to run
profile searches, while DCS.Search.Order.Index is used to run order searches.
Order and Profile Search Overview
The order and profile search configuration is comprised of the following:
• A routing component - The routing component allows you to create and administer search environments, as
well as handle the live updates of the index
• Indexing Output Configurations - An Indexing Output Configuration (IOC) is a component with an associated
definition file. The definition file is a standard XML document that defines the repository items, such as fields,
that create the search index. Separate indices are created for orders and profile, and as such, a definition
document is created for each index: profile-output-config.xml and order-output-config.xml.
• An Indexing Service - The Indexing Service tracks updates in a particular environment and passes information
to the routing component to ensure the index is updated.
• Indexed Items groups - The Indexed Items group defines the type of items that will be included in the index.
By default, only submitted orders will be indexed.
Indexing Methods
Order and profile search support both incremental and bulk indexing. Incremental indexing occurs in real time,
and as such, does not require an index deployment.
Incremental indexing is enabled by default, which is configured using the Indexing Service, to check for
modifications to profiles and orders every five seconds from multiple environments. During some operations,
18 3 Installing and Configuring ATG Commerce Service Center
such as modification, backup or restoration of an environment, incremental indexing is not available. During
these operations, incremental updates are queued until incremental indexing is restored.
Bulk indexing, which is started from the IOC component, recreates the complete index and is performed in a
temporary staging environment. When the bulk indexing job is completed, the temporary staging environment
is swapped with the live environment. During the time that the bulk index is running, searches are performed in
the live environment. However, incremental updates are queued and not applied until the bulk indexing job has
completed and the environments are swapped.
Profile and order require separate Search projects. This allows both profiles and orders to be indexed
concurrently as indexing jobs from separate search environments can be run in parallel.
Customer profile and order information is queued using IncrementalItemQueue, which obtains requests from
any server and are processed on the server(s) that executes the indexing request.
Note: Set the /atg/search/repository/IncrementalLoader/
recordIncompleteOrderEvents to false to enable filtering of incomplete orders.
Order and Profile Search Components
The following components from DAF.Search.Index are used for order and profile searches. For additional
information on these components, refer to the ATG Search Installation and Configuration Guide.
• /atg/search/repository/IncrementalItemQueue
• /atg/search/repository/IncrementalItemQueueRepository
• /atg/search/repository/ConfigStatePersister
• /atg/search/repository/ConfigAndRepositoryPersister
• /atg/search/repository/IncrementalLoader - DPS.Search.Index appends the
ProfileOutputConfig to the monitoredOutputConfig property. DCS.Search.Order.Index
appends the OrderOutputConfig to the monitoredOutputConfig property. When the
IndexingPeriodicService runs, the IncrementalLoader will process queued indexing requests for the
OrderOutputConfig and ProfileOutputConfig.
• /atg/search/repository/BulkLoader
• /atg/search/repository/IndexingPeriodicService – Configured in DPS.Search.Index to
run every two seconds by default. All servers are configured with the IndexingPeriodicService
enabled but only indexes any OrderOutputConfig or ProfileOutputConfig that has the component
enableIncrementalLoading=true and incrementalUpdateSeconds>0. As such, you should only set the
incrementalUpdateSeconds>0 on servers that will be used for indexing.
The OrderOutputConfig.incrementalUpdateSeconds is set to 30 by default to ensure that at least
one server will process the queued incremental indexing requests. In a production environment, it is
recommended that you set incrementalUpdateSeconds=-1 on the agent-facing server and configure
incrementalUpdateSeconds>0 on the management server. Incremental indexing can be enabled on any
background server that is running DPS.Search.Index, and DCS.Search.Order.Index for servers.
The IndexingPeriodicService clears any expired configuration claim locks each time it runs using the
checkExpiredConfigurationClaimsIntervalSeconds property, which checks for expired configuration
claim locks every n seconds. Each time the IndexingPeriodicService runs, it checks if the time elapsed
has exceeded this interval
The following components are also used in the order and profile search process:
3 Installing and Configuring ATG Commerce Service Center 19
Component Description
/atg/userprofiling/search/
ProfileOutputConfig
The profile IndexingOutputConfig. Defined in the
DPS.Search.Index module so that an indexing request
can be queued wherever a profile is added or updated. The
component creates the profile-output-config.xml
definition file.
/atg/commerce/search/
OrderOutputConfig
The order IndexingOutputConfig. Defined in the
DCS.Search.Order.
Index module so that an order indexing request can
be queued wherever an order is added or updated. The
component creates the order-output-config.xml
definition file.
/atg/search/repository/
LiveDocumentSubmitter
A special document submitter that updates the index
in near real time. This component is defined in the
DAF.Search.Index module.
/atg/commerce/search/
OrderProfileIdPropertyAccessor
Uses the atg.repository.search.indexing.
accessor.ItemIdPropertyAccessor class that retrieves
properties from an item where the item is referenced by ID.
In this case, the order item references the user item by Profile
ID.
/atg/userprofiling/search/
AddressPropertyAccessor
Uses the atg.repository.search.indexing.
accessor.ConcatenatePropetyAccessor class to
concatenate address1, address2 and address3 into a
single indexed address meta property.
/atg/search/repository/
AlphaNumericPropertyAccessor
Removes non-alpha-numeric characters from the indexed
meta property. Used to strip white space and punctuation
from phoneNumber to promote better search consistency.
Configuring Servers for Search
For every server that creates, updates or deletes profiles or orders you must perform the following:
1. Add DPS.Search.Index and DCS.Search.Order.Index modules to the EAR file on the agent-facing
servers, if not already present. Also add these modules to the EAR file for your customer-facing and
management servers.
2. You must pick an internal server that will be your live indexing server. For a production environment, this
should be done on a dedicated server. Note: Only one server can be the indexing server. When creating
the live indexing server ensure that you have added the DAF.Search.Routing, DPS.Search.Index,
DCS.Search.Order.Index, DAF.Search.Index and DAFEar.Admin modules to the EAR file.
3. Edit the following properties files in the live indexing server /localconfig directory with the following
settings:
/localconfig/atg/commerce/pricing/pricelists/PriceLists.properties
/localconfig/atg/commerce/inventory/InventoryRepository.properties
/localconfig/atg/commerce/order/OrderRepository.properties
20 3 Installing and Configuring ATG Commerce Service Center
/localconfig/atg/userprofiling/ProfileAdapterRepository.properties
/localconfig/atg/content/Media/MediaRepository.properties
Add the following to the properties files:
idGenerator=/atg/dynamo/service/IdGenerator_production
lockManager=/atg/dynamo/service/ClientLockManager_production
dataSource=/atg/dynamo/service/jdbc/JTDataSource_production
subscriberRepository=/atg/dynamo/service/jdbc/SQLRepository_production
eventServer=/atg/dynamo/server/SQLRepositoryEventServer_production
4. Edit the following properties files in the live indexing server /localconfig directory with the following
settings:
/localconfig/atg/sitemap/SitemapRepository.properties
/localconfig/atg/dynamo/service/jdbc/SQLRepository.properties
/localconfig/atg/dynamo/security/AdminSqlRepository.properties
/localconfig/atg/userprofiling/PersonalizationRepository.properties
Add the following to the properties files:
idGenerator=/atg/dynamo/service/IdGenerator_agent
lockManager=/atg/dynamo/service/ClientLockManager_agent
eventServer=/atg/dynamo/server/SQLRepositoryEventServer_agent
5. Modify the following settings on the live indexing server property files:
Edit the /localconfig/atg/search/routing/repository/
SearchConfigurationRepository.properties file:
dataSource=/atg/dynamo/service/jdbc/JTDataSource_production
subscriberRepository=/atg/dynamo/service/jdbc/SQLRepository_production
Edit the /localconfig/atg/search/service/
SearchSQLRepository.properties file:
componentPath=/atg/dynamo/service/jdbc/SQLRepository_production
Edit the /localconfig/atg/search/service/
SearchSQLRepositoryEventServer.properties file:
componentPath=/atg/dynamo/server/SQLRepositoryEventServer_production
Edit the /localconfig/atg/search/service/SearchIdGenerator.properties file:
componentPath=/atg/dynamo/service/IdGenerator_production
Edit the /localconfig/atg/search/service/
SearchClientLockManager.properties file:
componentPath=/atg/dynamo/service/ClientLockManager_production
6. Disable the caching of external user items on the profile live indexing server. The profile adapter repository
uses simple caching, which means that the live indexing server will not detect changes to the user. To ensure
that all changes are detected, disable caching on the live indexing server by editing the /localconfig/atg/
userprofiling/userProfile.xml file:
<gsa-template>
3 Installing and Configuring ATG Commerce Service Center 21
<item-descriptor name="user" cache-mode="disabled" />
<item-descriptor name="contactInfo" cache-mode="disabled" />
</gsa-template>
7. Disable caching of order items on the order live indexing server. The order repository uses simple caching;
as such the live indexing server will not detect changes to the order, particularly to the status change of the
order. To ensure that that the live indexing server detects changes correctly, disable caching by defining the
following in the /localconfig/atg/commerce/order/orderrepository.xml file. These modifications
will disable caching for the order and user (and referenced items) so that when updated on the customer-
facing server, the new values will be read on the live indexing server and the current value will be indexed.
<gsa-template>
<item-descriptor name="order" cache-mode="disabled" />
<item-descriptor name="shippingGroup" cache-mode="disabled" />
<item-descriptor name="hardgoodShippingGroup" cache-mode="disabled" />
<item-descriptor name="electronicShippingGroup" cache-mode="disabled" />
<item-descriptor name="paymentGroup" cache-mode="disabled" />
<item-descriptor name="creditCard" cache-mode="disabled" />
<item-descriptor name="giftCertificate" cache-mode="disabled" />
<item-descriptor name="storeCredit" cache-mode="disabled" />
<item-descriptor name="paymentStatus" cache-mode="disabled" />
<item-descriptor name="creditCardStatus" cache-mode="disabled" />
<item-descriptor name="giftCertificateStatus" cache-mode="disabled" />
<item-descriptor name="storeCreditStatus" cache-mode="disabled" />
<item-descriptor name="commerceItem" cache-mode="disabled" />
<item-descriptor name="configurableCommerceItem" cache-mode="disabled" />
<item-descriptor name="subSkuCommerceItem" cache-mode="disabled" />
<item-descriptor name="handlingInstruction" cache-mode="disabled" />
<item-descriptor name="giftlistHandlingInstruction"
cache-mode="disabled" />
<item-descriptor name="relationship" cache-mode="disabled" />
<item-descriptor name="shipItemRel" cache-mode="disabled" />
<item-descriptor name="payShipRel" cache-mode="disabled" />
<item-descriptor name="payOrderRel" cache-mode="disabled" />
<item-descriptor name="amountInfo" cache-mode="disabled" />
<item-descriptor name="orderPriceInfo" cache-mode="disabled" />
<item-descriptor name="itemPriceInfo" cache-mode="disabled" />
<item-descriptor name="taxPriceInfo" cache-mode="disabled" />
<item-descriptor name="shippingPriceInfo" cache-mode="disabled" />
<item-descriptor name="detailedItemPriceInfo" cache-mode="disabled" />
<item-descriptor name="pricingAdjustment" cache-mode="disabled" />
<item-descriptor name="marker" cache-mode="disabled" />
<item-descriptor name="commerceItemMarker" cache-mode="disabled" />
<item-descriptor name="manualPricingAdjustment" cache-mode="disabled" />
<item-descriptor name="OrderFixedAmountAdjustment"
cache-mode="disabled" />
<item-descriptor name="scheduledOrderError" cache-mode="disabled" />
</gsa-template>
8. You must configure the processing of live indexing requests. Set the following properties in the /
localconfig directory of the CSC and the agent servers:
/atg/userprofiling/search/ProfileOutputConfig
incrementalUpdateSeconds=-1
/atg/userprofiling/search/OrderOutputConfig
22 3 Installing and Configuring ATG Commerce Service Center
incrementalUpdateSeconds=-1
Set the following properties in the /localconfig directory of the management server:
/atg/userprofiling/search/ProfileOutputConfig
incrementalUpdateSeconds=5
/atg/userprofiling/search/OrderOutputConfig
incrementalUpdateSeconds=5
By setting incrementalUpdateSeconds to a positive value, you enable incremental indexing of profiles
or orders on the management server. The value you enter is the frequency to check for profiles or orders to
index. The value you set depends on how often you need the profile or order indexed.
9. Set the following /localconfig/atg/search/routing/
LaunchingService values on your indexing and agent-facing servers. The deployment share directory is
a single shared directory where master copies of indexes are stored. For additional information, refer to the
Installing ATG Search chapter of the ATG Search Installation and Configuration Guide:
deployShare=drive:/yourSharedDirectory/yourDeployShareMainDirectory
engineDir=drive:/path to Search Engine
For example:
deployShare=C:\ATG\DeployShareMain
engineDir=C:\ATG9\Search9.4\SearchEngine
10.To create a full index, the indexing engine requires a clean partition. The clean partition is a file from which
all indexes are created. As such, you need to identify the location of the clean partition by creating a /
localconfig/atg/search/routing/
RoutingSystemService.properties file. Use the cleanPhysicalPartitionPath property to identify
the full path to the clean partition.
There is a copy of the clean partition located at <Searchdir>/SearchEngine/
operatingsystem/data/initial.index. To resolve the path correctly, use a relative path to identify the
clean partition location as a local copy. For example:
cleanPhysicalPartitionPath =../data/initial.index
For additional information, refer to the Configuring Remote Indexing Engines section in the ATG Search
Installation and Configuration Guide.
Configuring Search Environments
Each Search project creates an indexing environment on the local machine. Configuration of order and profile
search is done using the Dynamo Admin UI. For additional information on search environments, refer to the
Managing Search Environments chapter of the ATG Search Administration Guide.
1. On your Search server, start the remote server by running the /Search/Search9.4/SearchAdmin/bin/
startRemoteLauncher script.
2. Open the Dynamo Admin UI at http://hostname:port/dyn/admin/nucleus/
atg/search/routing/LiveIndexingService/
3. Click the Create a new live indexing environment link. Two buttons appear for creating Order and Profile
search environments.
3 Installing and Configuring ATG Commerce Service Center 23
4. Click the buttons to create one of the environments and enter the details of your search engine. You can
either select the check box for your existing machine or enter the address of another machine.
5. Repeat steps 3 and 4 to create additional indexing environments.
6. Click the Environments link to display the current default environments. Two environments, a live indexing
and a bulk index, are created for both Profile and Order processes.
Note: If you choose different environment names than the default ATGProfile and ATGOrder, you must
edit the /atg/userprofiling/search/
ProfileSearchConfiguration and /atg/commerce/search/
OrderSearchConfiguration components to reflect the search environment names and corresponding
logical partition names.
7. Use the Environment page to manage your environments.
Installing Reporting
ATG Commerce Service Center has the capacity to collect information that can be added to a report. For
information on installing and configuring ATG Reporting, refer to the ATG Customer Intelligence Installation and
Configuration Guide.
To install ATG Reporting for CSC, perform the following steps on a separate load server:
1. Run the following SQL files for the data warehouse and loader:
ARF/base/sql/db_components/db_type/arf_loader_ddl.sql
24 3 Installing and Configuring ATG Commerce Service Center
ARF/base/sql/db_components/db_type/arf_id_generator.sql
ARF/DW/base/sql/db_components/db_type/arf_ddl.sql
ARF/DW/base/sql/db_components/db_type/arf_init.sql
DCS/DW/sql/db_components/db_type/arf_dcs_ddl.sql
DCS/DW/sql/db_components/db_type/arf_dcs_init.sql
Service9.4/Service/DW/sql/db_components/db_type/svc_dw_ddl.sql
2. Create the EAR file by running a command similar to the following from <ATG9dir>/bin directory. The DCS-
CSR.DW module will enable Reporting:
runAssembler DCSCSR.ear –m DafEar.Admin DCS-CSR.DW
Enabling Report Data Collection
ATG Commerce Service Center can collect customer and order information, allowing you to generate reports
using ATG Reporting Center. Enable the report data collection process by adding enabled=true to the
localconfig/atg/dynamo/service/DeploymentDWDataCollectionConfig.properties file on the asset
management and the agent-facing servers.
The metadata model for reports can be found in the <ATG9dir>/CSC9.4/DCS-CSR/DW/deployment/
Commerce Service.zip file.
Accessing ATG Commerce Service Center
You can access ATG Commerce Service Center at the following URL:
http://hostname:port/agent
The hostname is the name of the machine on which ATG Commerce Service Center is running. The port is the
port number that your application server uses to listen for requests; see the ATG Installation and Configuration
Guide for your application server for the default port number.
4 Configuring eStara Click to Call 25
4 Configuring eStara Click to Call
eStara Click to Call is an optional application that, when integrated with ATG Commerce Service Center, initiates
and manages telephone communication between agents and customers.
eStara Click to Call Integration Overview
eStara Click to Call integration with CSC enables customers to initiate phone calls with agents. Once configured,
eStara uses a page instrumentation engine to add JavaScript into your customer-facing web pages. The
JavaScript presents an icon and/or link to the customer who uses this link to enter a phone number that the
eStara Webcare system or an optional CTI system uses to return their call. CSC presents the agent with the
customer’s order information and profile, allowing the agent to assist the customer with their order.
Initiating a Call
When the customer initiates a call, their customer and order information is written to the ATG database. A
unique call identification number as well as the customer’s phone number are sent to eStara Webcare. This
information is transmitted using an ATG-eStara token that creates a unique identifier that correlates the call with
the customer’s call data. The token is passed to the eStara system and is used later to obtain the data for the call.
Once eStara has obtained the token, it establishes a call with both the telephony system (CTI) and the customer.
The telephony system initiates the call with the agent.
Once the agent or the CTI system has entered the phone number into a CSC Start Call screen, CSC obtains
the information about the call using an ATG-eStara token and presents the agent with the customer’s order
information. The agent then assists the customer as with any other CSC call.
Using a CTI System
Click to Call and CSC can be configured to work with or without a CTI system. With a CTI system, once the unique
call information has been obtained, the CTI system initiates a browser screen. The browser invokes a URL that
passes the caller ID as a query parameter. CSC looks up the call token from Webcare using the caller ID, looks up
the customer information using the call token, and configures the agent’s environment with the customer and
order information.
CSC also provides a mechanism for your CTI system to authenticate an agent. The CTI system can be configured
to pass the agent username to CSC for authentication. The authentication process requires that the system must
26 4 Configuring eStara Click to Call
pass a salted hash of the username for security. If you do not wish to configure authentication, agents can log in
to CSC manually using the CSC log in screen.
You can integrate your CTI system using eStara WinCare to obtain the caller ID information from a screen scrape.
To use WinCare, you need to install and configure the WinCare system on each agent’s desktop.
Specifying Links and Pop Ups
The eStara Webcare system, which is managed and maintained by eStara, creates and configures links that are
presented to the customer. These popup icons and call information screens can be customized using logos,
graphics and other UI components that are stored locally on your servers.
Links and pop ups can be static or based upon rules that you create using the Webcare Rule Builder tool or
the ATG rule process. For example, you can create a rule that presents a link when a customer is from a specific
country, or that pops up a Click to Call icon if a customer’s shopping cart has reached a specific amount.
Automatic Initialization of the Agent’s Working Environment
Part of the process of receiving a call in CSC is to initialize the agent’s working environment with the correct set
of object.
By default, the following values are saved when a call is initiated on the store front and then used to pre-
populate the agent’s working environment with the correct set of the objects:
• Profile ID – used to load the active customer
• Order ID – used to load the active order
• List Pricelist ID – used to load the active list price list
• Sales Pricelist ID – used to load the active sale price list
• Catalog ID – used to load the active catalog
eStara Click to Call Requirements
There is no license requirement for Click to Call. However, you must have an active eStara account. Contact your
eStara account manager for further information.
The following modules are required to run eStara Click to Call and should be installed on the agent-facing server:
• DCS-CSR.ClickToConnect
• Service.ClickToConnect
The following modules should be installed on the customer-facing server:
• DCS.ClickToConnect
4 Configuring eStara Click to Call 27
Configuring the eStara Account
Before you can set up Click to Call on either your store-facing pages or CSC, you must provide CSC with eStara
account information.
Note: Before completing these steps, you must have a valid and active account with eStara.
1. Configure CSC to recognize your eStara account information by editing the localconfig/atg/
clicktoconnect/Configuration.properties file.
2. Add your eStara account ID, user name and password to the file.
# Your eStara account ID
accountId=eStara Account ID
# The eStara ClickToConnect username
username=eStara User Name
# The eStara ClickToConnect password
password=eStara Password
3. Save the file when you’ve finished.
Adding an Agent to CSC
eStara agents must be added to CSC. The login name for agents must be the same on both Click to Call and CSC.
Use the ATG BCC to add eStara agents to CSC. Refer to the ATG Business Control Center User’s Guide for additional
information in creating users.
Adding Agent Phone Numbers
When creating pop ups and links using the eStara Webcare Link Builder tool, you will need to provide the
phone number of the call center, and if necessary, extension information. Refer to the eStara Link Builder Tool
documentation and the Creating a Click to Call Link (page 31) section for additional information.
Configuring Customer-Facing Store Web Pages
To run Click to Call with CSC, you must add automatic page instrumentation filters. To create static links, you
must create the button or link tag that will access Click to Call on your customer-facing store web pages.
Configuring Automatic Page Instrumentation
Automatic page instrumentation allows you to automatically tag each of your customer-facing store web
pages with the eStara JavaScript library references, as well as to output other parameters that are used for
data persistence purposes without changing any code for your site. When configuring automatic page
instrumentation, you set the page instrumentation filters that are used to add the eStara code to your pages.
28 4 Configuring eStara Click to Call
The page instrumentation engine writes JavaScript variables to the web page. These variables are used to
identify the customer’s environment and to store information that allows you to create customized rules that
display links and pop ups based on specific criteria. For example:
var _atg_estara_call_token=100001-1234;var _atg_estara_locale=en_US;
Adding Automatic Page Instrumentation
To add automatic page instrumentation, add the following to your customer-facing store’s web.xml file:
<filter> <filter-name>ADCDataInsertFilter</filter-name> <filter-class>atg.filter.ConditionalDelegatingFilter</filter-class> <init-param> <param-name>targetFilter</param-name> <param-value>atg.adc.filter.ADCDataInsertFilter</param-value> </init-param></filter><filter-mapping> <filter-name>ADCDataInsertFilter</filter-name> <url-pattern>*.jsp</url-pattern></filter-mapping>
Configuring a Static Link
To configure a static link, or a link that remains within a navigational pane or frame within your web pages, you
must add a <div> tag in the page HTML where the link should appear. This section holds information that you
create in eStara Webcare. The following example inserts a <div> that has a specific border style.
<div id="eStara_ClickToCall_Link" style="border: 1px solid rgb(0, 0,0);"></div>
Once you have created a <div>, the <div> tag IDs is used by the link definitions that you define in eStara
Webcare. Refer to the Creating a Click to Call Link (page 31) section for additional information on creating
links.
Disabling the Orphaned Session Service
The OrphanedSessionService removes orphaned session items from the ClickToConnect session
repository. By default, the service is configured with the DCS.ClickToConnect module set to enabled=true
and the Service.ClickToConnect configuration set to enabled=false. This service should be started on any
instance where you have installed the DCS.ClickToConnect module and disabled on any instance configured
with the Service.ClickToConnect module.
You can disable the service by setting the /atg/clicktoconnect/OrphanedSessionService.
properties file enabled property to false in your /localconfig directory.
4 Configuring eStara Click to Call 29
Creating Store-Facing eStara Links
You integrate the CSC and Click to Call applications using eStara rules. Using the eStara Webcare Rule Builder
tool, you must create the following rules. For additional information on creating eStara rules, refer to the eStara
documentation.
Using the clickToConnectSave() Function
The clickToConnectSave() function is a JavaScript call that is located on each page of your customer-facing
site. The function persists both order and token information in ATG. The eStara JavaScriptCallBack rule looks
for the clickToConnectSave function on your page, and controls when to run it. The clickToConnectSave
function is created automatically when you run the eStara page instrumentation and does not need to be added
manually to every page. However, the clickToConnectSave function can also be configured using the eStara
Webcare Rule Builder tool.
Creating the JavaScriptCallback Rule
When you create the JavaScriptCallback rule, modify the following fields. Other fields can remain at their
default. For additional information on the fields, refer to the eStara Webcare Rule embedded assistance.
1. Log into the eStara Webcare website.
Note: In order to log into the Webcare website, you must have an existing eStara account.
2. From the Setup menu, select Rule Builder.
3. Click the Add a New Rule link.
4. Use the Name field to create the name of the rule. Enter JavaScriptCallback.
5. The Applies To field should be set to Both Customers and Agents using the pull down menu.
6. Enable the rule by clicking the Yes radio button in the Enabled field.
7. Set the Rule Operating Hours to All Hours to ensure that the rule is always run.
8. Set the Link to Show field to No Link, as this rule will not display a link.
9. Using the URL Match field, enter a regular expression to indicate to which URL the rule applies. To ensure that
the rule applies to all URLs on your site, select the use check box and enter .* in the text field.
10.The JavaScriptCallback rule is a RunJavaScript Rule Type. This rule runs the specified JavaScript. Select
RunJavaScript from the drop down menu.
11.Click the Show Advanced Feature button to display the arguments that are required when using the
RunJavaScript rule type.
12.In the Argument 1 field, enter the name of the function to be called with its associated parameters. Enter
clicktToConnectSave()
13.Ensure that Argument 2 field is set to use the default, which is 0. This argument will run the function
whenever the link is clicked.
14.Save the rule
30 4 Configuring eStara Click to Call
ATGeStaraCallToken
When the customer clicks the eStara link or button, a unique token ID is generated and stored using the
clickToConnectSave function. This token, which is stored in the _atg_estara_call_token variable
in the ATGeStaraCallToken rule, is used to identify the information that the customer was viewing. The
ATGeStaraCallToken rule then passes the token to eStara.
Once the call is initiated, CSC requests the call token from eStara Webcare using the caller ID and looks
up the customer information in the atg/clicktoconnect/Click to CallRepository. The end user
information that was stored with the tolkenID is then presented to the agent. The token is created by the page
instrumentation filter, and is then passed to Webcare using the ATGeStaraCallToken rule.
Creating the ATGeStaraCallTokenRule
When you create the ATGeStaraCallToken rule, modify the following fields. Other fields can remain at their
default. For additional information on the fields, refer to the eStara Webcare Rule embedded assistance.
1. Log into the eStara Webcare website. From the Setup menu, select Rule Builder.
2. Click the Add a New Rule link. Use the Name field to create the name of the rule. Enter
ATGeStaraCallToken.
3. The Applies To field should be set to Both Customers and Agents using the pull down menu.
4. Enable the rule by clicking the Yes radio button in the Enabled field.
5. Set the Rule Operating Hours to All Hours to ensure that the rule is always run.
6. Set the Link to Show field to No Link, as this rule will not display a link.
7. Using the URL Match field, enter a regular expression to indicate to which URL the rule applies. To ensure that
the rule applies to all URLs on your site, select the use check box and enter .* in the text field.
8. The ATGeStaraCallToken rule is a VarFieldMatch Rule Type. Select VarFieldMatch from the drop down
menu.
The VarFieldMatch rule checks every two seconds to verify that the field name you specify in the Argument
1 field matches the regular expression entered in the Argument 2 field and is stored in the variable identified
in Argument 3.
9. Click the Show Advanced Feature button to display the arguments that are required when using the
VarFieldMatch rule type. In the Argument 1 field, enter the name of the JavaScript variable to verify. Enter
the JavaScript variable _atg_estara_call_token.
10.The Argument 2 field sets the expected value returned by the JavaScript variable. Use the \s* regular-
expression to indicate that the _atg_estara_call_token is always valid.
11.The Argument 4 field sets the variable name in which the value is stored. Set the variable field to 1, indicating
that the value returned in Argument 2 is stored in var1.
12.Save the rule.
Creating Store-Facing Static Click to Call Links
Using the eStara Webcare application, you create customer-facing Click to Call links , which are used by
customers to initiate a call,. Click to Call links can be generic, which present the same links to all of your
4 Configuring eStara Click to Call 31
customers, or they can be customized. Customized links allow you to configure not only the links, but the
presentation and the specific audience for each link.
Creating a Click to Call Link
Click to Call links live within the HTML of your customer-facing web page. For example, you can place a static link
in one of your existing navigational menus using a <div> tag.
When creating a static Click to Call link, you create a Timeout Link that has a time out length of zero (0),
indicating that the link is displayed whenever the page is rendered. Then you identify the link icon and the
location of the link on your commerce page by specifying the ID of a <div> on the page.
The majority of the Link Builder fields will use the default values. For additional information on the eStara Link
Builder tool, refer to the eStara documentation or the eStara field screen assistance. Modify the fields as outlined
below:
1. Create a <div> tag, as outlined above in the Configuring a Static Link (page 28) section. Record the ID of
the <div> as it will be used when creating the link.
2. Open eStara Webcare. Use the Set Up menu and select the Link Builder tool. From the Add New options,
select timeout to access the Link Customization screen.
You’ll use this screen to configure and customize the links that are presented to your customers.
3. Enter a Link Name.
4. Use the Link Type drop down menu to select Timeout.
The Timeout link type is used to display links that appear after a specific amount of time. Use the Timeout link
type to create a generic static link.
5. Enter the Language in which the link will be presented.
6. Enter the Phone Number of your call center or agent by selecting the country and entering the country code
and phone number.
7. Enter a UI Title. The title you provide will be displayed as the title bar in the browser when the customer
selects the link.
8. Select the Link Icon. You can select an existing link that is stored on the eStara site, or you can add a custom
URL that displays a custom icon. If you select the custom URL, enter the full DNS name of the link, the port
number and the path for the location of the icon. For example:
http://commerceserver1:8080/images/estara/clicktocallicon.gif
9. Use the Timeout in Seconds field to enter the amount of time that a customer is on your web page before the
link is made available. To configure a static link that is always available, the Timeout value should be set to 0.
10.Set the Positioning fields to 0 for the left and the top of the page. This allows the <div> you created to set the
location of the link.
11.In the Relative to Layer ID field, enter the ID of the <div> you created earlier. For example,
eStara_ClickToCall_Link.
12.Click Add Link to save the link. The new link is listed in the Link Summary table.
This sets a continual and static link in the <div> you created on your commerce web page.
32 4 Configuring eStara Click to Call
Creating a Click to Call Pop Up
Click to Call pop ups are links that live within the HTML of your customer-facing web page and appear when
specific criteria have been met. For example, you can create a popup that becomes available if your customer
has remained on a page for more than ten seconds.
When creating a timed Click to Call pop up, you create a Timeout Link that has a time out length indicating the
amount of time that the user remains on the page, for example ten (10) seconds. Then you identify the link icon
and the location of the pop up on your commerce page.
The majority of the Link Builder fields will use the default values. For additional information on the eStara Link
Builder tool, refer to the eStara documentation or the eStara field screen assistance. Modify the fields as outlined
below:
1. Open eStara Webcare. Use the Set Up menu and select the Link Builder tool. From the Add New options,
select timeout to access the Link Customization screen.
You’ll use this screen to configure and customize the links that are presented to your customers.
2. Enter a Link Name.
3. Use the Link Type drop down menu to select Timeout.
The Timeout link type is used to display links that appear after a specific amount of time.
4. Enter the Language in which the link will be presented.
5. Enter the Phone Number of your call center or agent by selecting the country and entering the country code
and phone number.
6. Enter a UI Title. The title you provide will be displayed as the title bar in the browser when the customer
selects the link.
7. Select the Link Icon. You can select an existing link that is stored on the eStara site, or you can add a custom
URL that displays a custom icon. If you select the custom URL, enter the full DNS name of the link, the port
number and the path for the location of the icon. For example:
http://commerceserver1:8080/images/estara/clicktocallpopup.gif
8. Use the Timeout in Seconds field to enter the amount of time that a customer is on your web page before the
link is made available. For example enter a time out value of 10.
9. Set the Positioning fields. Identify where on your webpage you want the pop up to appear and enter the
location in pixels.
For example, you can set the pop up to appear 650 pixels from the left of the page and 350 from the top of
the page.
10.Click Add Link to save the link. The new link is listed in the Link Summary table.
This sets a pop up link that appears if the customer has remained on your commerce web page for at least 10
seconds.
Creating a Customized Link or Pop Up
eStaralinks and pop ups can be configured to meet specific criteria using the Webcare Rule Builder tool. Rules
allow you to set up and configure conditions based upon specific customer behavior.
4 Configuring eStara Click to Call 33
Example: Creating a Link based on Locale
For example, you can display a French language static link to a customer in France, while displaying an English
language pop up link to a customer in the U.S.
The page instrumentation that you configured in the Adding Automatic Page Instrumentation (page 28)
section adds JavaScript variables to your web page. One of the variables added is the _atg_estara_locale
variable. This variable identifies the customer’s locale. You create a rule that uses a VarFieldMatch to see if
the JavaScript variable named by Argument 1 is equal to the value in Argument 2. If so, the rule will display its
associated link.
Using the French language example, to create a button that only renders for those customers who speak French,
the page instrumentation would write var _atg_estara_locale=fr_FR into the page when French is
chosen, a VarFieldMatch rule could be used to render the link by specifying fr_FR as the value for Argument
2. For an English speaker who lives in the United States, the VarFieldMatch rule could be used to render the
link by specifying en_US as the value for Argument 2.
To create an example customized static link that resides in a specific location on your customer-facing website:
1. Ensure that you have created a <div> tag in the HTML for your web server pages as outlined in Configuring a
Static Link (page 28).
2. Create a link, following the steps outlined above in Creating a Link. To create a French link, select French from
the Language drop down menu. For example, create a link named StaticFrenchLink that identifies the link
as a static link that displays in French.
3. Save the link.
4. Open the Webcare Rule Builder tool and click Add New Rule to create a new rule.
5. Name the rule. Use a name that identifies the rules function.
6. Ensure that the rule applies to both Customer and Agents, and that the rule is set to Enabled.
7. Enter the Link to Show. This is the link that you created in Step 3. For example, enter StaticFrenchLink.
8. Use the Rule Type pull down menu to select the VarFieldMatch rule type. This rule type will check to see if
the field identified in the Argument 1 field matches the regular expression identified in the Argument 2 field.
9. In the Argument 1 field, enter _atg_estara_locale. This retrieves the information regarding the customer’s
location.
10.Identify the language required by entering fr_FR in the Argument 2 field. This indicates that the language is
French, as spoken by a customer living in France.
11.The optional Argument 4 is used to pass the value of the matching JavaScript variable to eStara. The value
can later be retrieved from the eStara web service or it can be used in eStara reports.
12.Save the rule.
To create an example customized English language pop up link:
1. Create a link, following the steps outlined above in Creating a Generic Pop Up. To create an English pop up,
select English from the Language drop down menu. For example, create a link named EnglishPopUp that
identifies the link as a pop up link that displays in English.
2. Save the link.
34 4 Configuring eStara Click to Call
3. Open the Webcare Rule Builder tool and click Add New Rule to create a new rule.
4. Name the rule. Use a name that identifies the rules function.
5. Ensure that the rule applies to both Customer and Agents, and that the rule is Enabled.
6. Enter the Link to Show. This is the link that you created in Step 3. For example, enter EnglishPopUp.
7. Use the Rule Type pull down menu to select the VarFieldMatch rule type. This rule type will check to see if
the field identified in the Argument 1 field matches the regular expression identified in the Argument 2 field.
8. In the Argument 1 field, enter _atg_estara_locale. This retrieves the information regarding the customer’s
location.
9. Identify the language required by entering en_US in the Argument 2 field. This indicates that the language is
English, as spoken by a customer living in the United States.
10.The optional Argument 4 is used to pass the value of the matching JavaScript variable to eStara. The value
can later be retrieved from the eStara web service or it can be used in eStara reports.
11.Save the rule.
Example: Creating a Link based on Segments and Scenarios
You can create links or pop ups that target a specific audience, such as people who are most likely to adopt early
technology. You can create variables that display specific information to targeted audiences. By using the ATG
Scenario model, you create the scenario that identifies your target audience, and then modify your customer-
facing web page to include the <div> tags.
1. Create a <div> tag, as outlined above in the Configuring a Static Link (page 28) section. Record the name
of the <div> tag, as it will be used when creating the link.
2. From the ACC > Targeting > Project Name > Profile and Content Groups, create a user profile. For example,
create a user profile that identifies people between the ages of 15 and 30 that purchase early technology.
Name the profile something that is descriptive, such as EarlyAdopters.
3. Open Pages and Components > J2EE Pages and open your storefront file.
4. Open the clickToCallLink.jsp file. For example, the /navigation/gadgets/
clickToCallLink.jsp file. The store front page may resemble the following:
<dsp:page>
<!- - - if the click to call feature is disabled, this entire div can be
safely bypassed --- >
<c:choose>
<c:when test="$(not empty Click to CallConfig)">
<fmt:message var="itemLabel"
key="navigation_clickToConnect.PremiumTitle"/>
<fmt:message var="itemTitle" key="common.linkTitle">
<fmt:param value="$(itemLabel)"/>
</fmt:message>
<H3>$(itemLabel></H3>
<fmt:message var="itemLabel"
key="navigation_clickToConnect.QuestionsTitle"/>
<fmt:message var="itemTitle" key="common.linkTitle">
<fmt:param value="$(itemLabel)"/>
4 Configuring eStara Click to Call 35
</fmt:message>
<H3>$(itemLabel></H3>
</c:when>
</c:choose>
</dsp:page>
5. Use the Insert Servlet Bean icon to select the Switch droplet. Enter the name of the user profile you created in
step 1. For example, bean:/atg/userprofiling/
Profile.EarlyAdopters.
6. Enter the HTML that is displayed if the value is true. This value is the <div> tag that you created for people
who are members of the EarlyAdopters profile. For example:
<div id="atg_mystore_ClickToCallEarlyAdopters_link">
7. Enter the HTML that is displayed if the value is false. This value is the other <div> tag that you created for
people who are not members of the EarlyAdopters profile. For example:
<div id="atg_mystore_ClickToCall_link">
8. The code now resembles:
<dsp:page>
<!-- if the click to call feature is disabled, this entire div can be
safely bypassed -->
<dsp:importbean var="Click to CallConfig" bean="/atg/clicktoconnect/
Configuration"/>
<c:choose>
<c:when test="${not empty Click to CallConfig}">
<dsp:droplet name="/atg/dynamo/droplet/Switch">
<dsp:param bean="/atg/userprofiling/Profile.EarlyAdopters"
name="value"/>
<dsp:oparam name="true">
<div id="atg_mystore_ClickToCallEarlyAdopters_link">
</dsp:oparam>
<dsp:oparam name="false">
<div id="atg_mystore_ClickToCall_link">
</dsp:oparam>
</dsp:droplet>
</div>
<p style="height:30px"/>
</c:when>
</c:choose>
</dsp:page>
Once you have modified the .jsp file, you must create the links and rules that will display the information.
1. Create a link, following the steps outlined above in Creating a Generic Link. Ensure that the Relative to Layer
ID names the <div> you created earlier, for example: atg_mystore_ClickToCallEarlyAdopters_link.
Once you have created the link, save the link.
2. Open the Webcare Rule Builder tool and click Add New Rule to create a new rule.
3. Name the rule. Use a name that identifies the rules function.
4. Ensure that the rule applies to both Customer and Agents, and that the rule is set to Enabled.
36 4 Configuring eStara Click to Call
5. Enter the Link to Show. This is the link that you created in Step 9. For example, enter
StaticEarlyAdoptersLink.
6. Use the Rule Type pull down menu to select the VarFieldMatch rule type. This rule type will check to see if
the field identified in the Argument 1 field matches the regular expression identified in the Argument 2 field.
7. In the Argument 1 field, enter profile.profile name. This retrieves the information regarding the
customer’s profile. For example profile.earlyAdopters searches for the Early Adopter profile.
8. Identify whether the profile should be activated or not by entering true in the Argument 2 field. This
indicates that customer is a member of the profile.
9. The optional Argument 4 is used to pass the value of the matching JavaScript variable to eStara. The value
can later be retrieved from the eStara web service or it can be used in eStara reports.
10.Save the rule.
For information on creating segments, refer to the ATG Business Control Center User’s Guide and the ATG
Personalization Guide for Business Users.
For additional information on creating Rules in eStara, refer to the eStara documentation or the Webcare screen
field assistance.
Using eStara WinCare
eStara WinCare is the agent-facing console that manages agent and customer interactions. WinCare can be used
with an existing CTI infrastructure to allow your agents to interact with customers.
Integrating with eStara WinCare
To integrate eStara WinCare, create a WinCare tab using eStara Webcare. A new browser window that contains
the predefined URL is rendered using client-side integration with WinCare.
To create the browser window that links your WinCare system to both the CSC and Click to Call systems, you
must create a WinCare tab in Webcare. Login to eStara Webcare, and follow the steps outlined below.
1. Select the Account Admin -> WinCare Tabs menu.
2. Click Add a New Item. The Item editor will load. Enter information for the following fields:
• Label Name - This will name the WinCare tab
• URL – The URL that will be passed to WinCare. In the following example, replace the CSC Server name and
the CSC Server port with your specific server and port information:
https://as00.estara.com/webcare/system/
atgconnect.php?url=newwin://CSC-Server:port/agent/main.jsp
• Pushable – performs a page push from the window
• Service - enter call to activate Click to Call
4 Configuring eStara Click to Call 37
• Shared – indicates if the browser window will be reused
• After Connect - spawns the window after the session connects. Set the After Connect field to 1.
• Addressbar – identifies if a tab should be displayed in the address bar
• Favorites – indicates if a favorites bar should be displayed
• Include Params field – indicates that any parameters should be passed along with the URL. Set the Include
Params field to 1
3. A new browser window will be created using a predefined URL.
The URL contains the atgConnect.php script, which generates the URL required to log an agent into CSC
and initiate a Click to Call session.
Integrating without eStara WinCare
When you integrate Click to Call and CSC with an external CTI system, you need to provide the CTI system with a
URL that accesses the Click to Call information. Before you can configure the eStara portion of the configuration,
ensure that your external CTI system can produce a hash that CSC will be able to reproduce. Then, generate a
script, for example,
/** * * Generates the URL that is used to spawn a CSC instance passing the required * parameters for a Click To Connect Session * * @param pURL * The initial part of the CSC URL e.g. http://foo:8080/agent/main * @param pUsername * The username of the CSC user * @param pCallerID * The caller id of the customer * @return The fully qualified URL * */public URL generateURL(String pURL, String pUsername, String pCallerID) throws \MalformedURLException, UnsupportedEncodingException {
// hashKey is the secret key used to salt the hash, this secret key is also//configured within CSC and should be identical to what is used here.final String hashKey = "mySecretKey";
// hashingAlgorithim is the algorithm used to create the hash. The algorithm//should be the same as is configured within CSC in order for CSC to recreate the//hash.final String hashingAlgoritim = "SHA1";
// hashText is the information that the hash is created from, the Agent username,//customer telephone number and the hashKey.String hashText = pUsername + pCallerID + hashKey;String clickToCallURLString = "";String hashString = "";
/*
38 4 Configuring eStara Click to Call
* Create hash of the username, callerID and the hashKey. The Hashing algorithm * used is SHA1, matching the hashing algorithm that CSC is configured to use. */try { MessageDigest m = MessageDigest.getInstance(hashingAlgoritim); m.update(hashText.getBytes(), 0, hashText.length()); hashString = new BigInteger(1, m.digest()).toString(16).trim();} catch (NoSuchAlgorithmException nsae) {}
/* * The URL is created from the initial CSC URL e.g http://foo:8080/agent, the * clickToCallInit parameter, the Agent username, the hash value, and the * telephone number of the shopper who initiated the click to call session */clickToCallURLString += pURL + "?clickToCallInit=true&username=" + URLEncoder.encode(pUsername, "UTF-8") + "&hash=" + URLEncoder.encode(hashString, "UTF-8") + "&UserTelephoneNumber=" + URLEncoder.encode(pCallerID, "UTF-8");
URL clickToCallURL = new URL(clickToCallURLString);
return clickToCallURL;}
Once you have verified that your CTI system can produce the necessary hash and URL, create a script that
integrates your system. The script should:
1. Get the username, user telephone number, secret key, and CSC URL variables
2. Set the checkFTCallID property of the /atg/svc/clicktoconnect/C2CTools component to false on
the CSC server
3. Create a hash of the username, user telephone number, and the secret key
4. Spawn a web browser with a URL made up of the following:
• CSC URL (http://cscserver:port/agent/main.jsp)
• The clickToCallInit=true variable
• The agent user name
• The hash made earlier
• The customer telephone number
Manual CTI Integration
If you are using a CTI system that only displays a telephone number on a physical device, the agent must
perform the following steps:
1. Log into CSC.
2. Enter a telephone number into the call field of the CSC user interface.
3. Press the Start Call button to perform a lookup. If a valid number has been entered, they must initiate a Click
to Call session.
4 Configuring eStara Click to Call 39
Note: Manual entry of the phone number requires the exact customer telephone number, including the area
code as CSC checks the phone number against the number that stored for that customer on the eStara server.
For international dialing codes, the 00 or the + is not required.
Configuring CSC Authentication with WinCare
CSC authenticates the data request and the agent user ID before transferring any data. CSC authentication uses
values that are calculated based on values in the request and a secret key value. You specify the secret key value
when working with eStara to set up your eStara account.
Enabling CSC Auto-Authentication
1. You can configure CSC to automatically authenticate an agent setting the atg/dynamo/servlet/daf/
pipeline/AuthenticaionServlet.properties file property enabled parameter to true.
2. A salted hash is generated by your CTI application or by eStara WinCare and then verified by Click to Call
to ensure authenticity. The secret key must be configured identically on both CSC and your CTI or WinCare
system. The property secretKeyForHashCompare in the /atg/svc/clicktoconnect/
C2CTools file should be set to the value of this key.
# salt for the hash that is generated
secretKeyForHashCompare=secretKey
3. eStara WinCare agents must be added with an identical login name for both CSC and Webcare for automatic
authentication. Use the BCC and Webcare to ensure that agent names are the same in both applications.
Note: If you are not using WinCare, set the checkFTCallID property to false in the /localconfig/atg/
svc/clicktoconnect/Click to CallTools file.
4. Use the eStara Webcare tool to add the agents. Contact your eStara account representative to set up the
secret key value. Refer to the eStara documentation for additional information.
5. Each agent must have a copy of eStara WinCare that is used to route telephone calls on their system.
Download the WinCare software from the eStara website at https://Webcare.eStara.com/wincare.
Disabling CSC Auto-Authentication
You can disable CSC authentication by setting the enabled property in the atg/dynamo/servlet/daf/
pipeline/AuthenticaionServlet.properties to false. Once authentication has been disabled, the agent
must log in for each session of CSC.
Configuring CSC Landing Page Components
Landing pages are used to control which page is initially viewed by the agent at the start of the Click to Call call.
Typically, landing pages are determined based on the URL viewed on the store front when the call was initiated.
However, the Landing Page components provide a generic interface that allows you to determine a landing
page based on other values, and not just the store front URL.
40 4 Configuring eStara Click to Call
Because most of the time the landing page is determined by the store front URL at the time the call was initiated
by the customer, CSC provides a number of LandingPage and LandingPageHandlers pre-configured to land
on specific views within the CSC application. This includes a default landing page that is used when no other
landing page is provided.
LandingPage configurations are available for landing the follow views in CSC. Any one of the provided
LandingPages can be mapped to one or more store front URLs.
• The shopping cart view of the active order
• The customer profile view of the active customer
• The existing order view for a given order
• The product view for a given product
• The main catalog browse view
Default Landing Page
The Default Landing Page determines which page is initially viewed when no other Landing Page can be
determined. By default, the Default Landing Page is configured with the shopping cart view.
Customizing Landing Page Components
You can change the default tab or panel that is presented to the agent when Click to Call presents a new call.
The following section describes the components and configurations for this feature.
The landing page configuration consists of the LandingPageManager, the LandingPageHandler and the
LandingPage components.
The LandingPageManager Component
The /atg/svc/clicktoconnect/LandingPageManager component contains the configurations for all of
the LandingPageHandlers and executes them to determine the correct landing page for the Click to Call
request. It polls all LandingPageHandlers until one of them returns a LandingPage object. If no landing page
is returned, the defaultLandingPageHandler is used.
These LandingPageManager properties are configurable as follows. If the LandingPageManager does not
successfully determine a LandingPage, the agent’s normal login landing page will be the default landing page:
• landingPageHandlers - an array of LandingPageHandler components
• defaultLandingPageHandler - the LandingPageHandler that is executed when no other
LandingPageHandler has provided a landing page
For example:
landingPageHandlers+= /atg/commerce/custsvc/clicktoconnect/ProductViewLandingPageHandler,\ /atg/commerce/custsvc/clicktoconnect/OrderViewLandingPageHandler,\ /atg/commerce/custsvc/clicktoconnect/CategoryViewLandingPageHandlerdefaultLandingPageHandler=/atg/commerce/custsvc/clicktoconnect/DefaultLandingPageHandler
4 Configuring eStara Click to Call 41
The LandingPageHandler Components
The LandingPageHandler components, which are integrated with LandingPageManager, return a
LandingPage based on the values of the Click to CallRequestData object.
The following LandingPageHandler properties are configurable:
• landingPage - the landingPage object that is returned by the
LandingPageHandler
• URIMatches - this property is available to LandingPageHandlers that determine the landing page based on
the current store front URL
Note: When configuring the URIMatches property, you must supply the full file path, for example /
commerce2/myaccount/profile.jsp.
Component Description
/atg/svc/clicktoconnect/
ProfileViewLanding
PageHandler
This component returns a landing page if the store front URL
starts with any one the strings specified by the URIMatches
property. The profile viewed will be the same as the profile saved
when initializing the call on the store front.
For example:
URIMatches=/ondemand/myaccount/profile.jsp
/atg/commerce/custsvc/
clicktoconnect/CategoryView
LandingPageHandler
This component returns a landing page if the store front URL
starts with any one the strings specified by the URIMatches
property. This component will land the agent on the catalog
browse main page.
For example:
URIMatches=/ondemand/subcategory.jsp?categoryId=
/atg/commerce/custsvc/
clicktoconnect/OrderView
LandingPageHandler
This component returns a landing page if the store front URL
starts with any one the strings specified by the URIMatches
property. The order ID is identified by a parameter on the
store front URL with the name specified by the property
orderIdParameterName. This component has a LandingPage
configuration for standard orders and another for scheduled
orders.
For example:
URIMatches=/ondemand/myaccount/myOrders.jsp
/atg/commerce/custsvc/
clicktoconnect/ProductView
LandingPageHandler
This component returns a landing page if the store front URL
starts with any one the strings specified by the URIMatches
property. The product ID is identified by a parameter on the
store front URL with the name specified by the property
productIdParameterName.
For example:
URIMatches=/ondemand/productDetailWithPicker.jsp?
productId=
42 4 Configuring eStara Click to Call
Component Description
/atg/commerce/custsvc/
clicktoconnect/
DefaultLandingPageHandler
This component returns a landing page when no other landing
page is provided. If the order is modifiable the cart view page is
used, otherwise the order view page is used.
For example:
scheduledOrderViewLandingPage=
ScheduledOrderViewLandingPage
orderViewLandingPage=OrderViewLandingPage
cartViewLandingPage=CartViewLandingPage
The LandingPage Component
A LandingPage object provides all of the information required for the LandinPageManager to initialize
the agent UI on a specific view. CSC provides a number of pre-configuration LandingPage components that
are used by the LandingPageHandlers. However, LandingPage objects can be constructed dynamically at
runtime.
The following properties are configurable in the LandingPage component:
• tabId
• panelStackIds
• panelIds
• dynamicIncludes
• treeTableIds
The following LandingPage components are available for configuration:
Component Description
/atg/svc/clicktoconnect/
ProfileViewLandingPage
Identifies the values required to land on the
customer tab’s profile view page.
/atg/commerce/custsvc/clicktoconnect/
CategoryViewLandingPage
Identifies the values required to land on the
commerce tab’s catalog view page.
/atg/commerce/custsvc/clicktoconnect/
ProductViewLandingPage
Identifies the values required to land on the
commerce tab’s product view page.
/atg/commerce/custsvc/clicktoconnect/
OrderViewLandingPage
Provides the values needed to land on the
commerce tab’s order view page.
/atg/commerce/custsvc/clicktoconnect/
ScheduledOrderViewLandingPage
Identifies the values needed to land on the
commerce tab’s scheduled order view page.
/atg/commerce/custsvc/clicktoconnect/
CartViewLandingPage
Provides the values required to land on the
commerce tab’s cart page.
5 Configuring ATG Commerce Service Center 43
5 Configuring ATG Commerce Service
Center
This chapter describes the following ATG Commerce Service Center tasks that you perform as an administrator:
Note: To set up return reason codes and returned item dispositions, use the Customer Service task area on the
main menu of the ACC.
Configuring Returnable Order States
ATG Commerce Service Center allows the modification of submitted orders that have not been fulfilled, as well
as returns and exchangesto orders that have been fulfilled.
1. To identify what orders can be returned, edit the modifiable and returnable-order states using the following
component:
# /atg/commerce/custsvc/order/OrderIsReturnable
shippingGroupShippedStates=NO_PENDING_ACTION
2. Configure which order states are not modifiable using the following component:
# /atg/commerce/custsvc/order/OrderIsModifiable
nonModifiableOrderStates=REMOVED,
QUOTED,
NO_PENDING_ACTION,
PENDING_REMOVE,
PENDING_CUSTOMER_RETURN
nonModifiablePaymentGroupStates=REMOVED,
SETTLED
Working with Exchange Orders
When an agent performs an exchange process and exchange order is created. Relevant payment groups must
be copied from the original order to the exchange order. The following payment groups are copied from the
original order:
44 5 Configuring ATG Commerce Service Center
• Credit Card – copied by default from the original to the exchange order
• Store Credit – copied if there a remaining amount
• Gift Certificate – copied if there is a remaining amount
To copy additional payment group types, add the payment group type to the
PaymentGroupCopyManager.properties file.
/atg/commerce/custsvc/returns/PaymentGroupCopyManager.properties## ServiceMap of paymentGroupTypes to Copier Nucleus componentscopiers+=\newPaymentGroupType=Component to copy new payment group
Note: The newPaymentGroupType should be one of the supported payment group types, outlined in the atg/
commerce/order/OrderTools.paymentTypeClassMap file.
For additional information, refer to the Customizing Shipping and Payment Group Types (page 86) section.
Configuring Return Shipping Addresses
To configure the shipping address for returns, perform the following steps:
1. 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>
2. 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
3. Save the ReturnShippingAddressRenderer.properties file.
For additional information on working with renderers, refer to the Configuring Pages with Nucleus
Components (page 110) section.
5 Configuring ATG Commerce Service Center 45
Setting up Return Reason Codes
Return reason codes must be set up and configured before an agent can perform a return or exchange. Reason
codes identify a reason for the return and are comprised of descriptions and corresponding ID numbers. Agents
select reason codes when performing a return. The selected reason code is stored within the record of the
customer’s exchange or refund.
The return reason item descriptor uses the following two properties:
• Description – describes the return reason, such as ‘Damaged’ or ‘Wrong Color’ and contains the resource key
• Readable description – The readableDescription property, which uses any given resource bundle and
user-defined property type to make the data in the resource bundle accessible through the repository API.
Note that the readableDescription property does not appear in the ‘New Item’ dialog box in the ACC
Once reason codes have been captured by the system, the system accesses the readableDescription
property, which refers to the reason code identified in the ReasonDescriptionPropertyDescriptor
property. This code accesses the description property and uses it as a key to look up the verbose description
in the resource bundle, which is named in the resourceBundle attribute of the readableDescription
property. The verbose string from the resource bundle will be the final text displayed.
Configuring Return Reason Codes
Return reasons are configured by performing the following steps:
1. Add a returnReasons item to the /atg/commerce/custsvc/
CSRRepository. For example, the following will add a return reason of “Competitor Beat Price”:
<add-item item-descriptor="returnReasons"
repository="/atg/commerce/custsvc/CsrRepository">
<set-property name="description" value="competitorBeatPrice"/>
</add-item>
2. To add a new reason codes, copy all of the existing reason codes from the
atg.commerce.csr.returns.ReturnReasonMessages.properties file to a new properties file. Then
add any new reason codes to this file. The newly created resource file should be set in the resourceBundle
attribute. The description property should contain the resource key. The atg.commerce.csr.returns.
ReasonDescriptionPropertyDescriptor property uses this value as a key when returning reason codes
from the resource bundle. Continuing with the Competitor Beat Price example:
#atg.commerce.csr.returns.ReturnReasonMessages.properties
competitorBeatPrice=Competitor Beat Price
3. You can specify a new resource bundle by changing the resource bundle specified in the CSRRepository
definition file:
<item-descriptor name="returnReasons">
<property name="readableDescription">
<attribute name="resourceBundle" value="com.example.MyResourceBundle"/>
</property>
</item-descriptor>
Creating Return Reason Codes
Note: Create reason codes in the development environment and push them to the production environment.
46 5 Configuring ATG Commerce Service Center
1. Using the ATG Control Center, select the Customer Service task area from the main ATG Control Center menu.
2. Select Return Reason Codes from the Customer Service submenu.
The system displays the Return Reason Codes screen. Click List to display all existing return reasons.
3. Click New Item to access the New Item dialog box.
4. Enter a return reason in the Description text box (for example, poorQuality).
Using the description resource key, the readable reason description will display in the Reason for Returning
Item drop-down list on the Create Exchanges and Returns page.
5. You can also enter an ID (or code) for the return reason in the New ID field. If the New ID field is left blank, the
system will automatically generate an ID.
6. Click OK to create the reason code.
7. Once you have created the return reason codes, you must create a resource bundle that contains your
environment specific settings. For information on creating resource bundles, refer to the Using Resource
Bundles for Internationalization section of the ATG Programming Guide.
5 Configuring ATG Commerce Service Center 47
Setting up Returned Item Dispositions
When an agent processes the receipt of a returned item, the agent assigns an action that should occur with the
return. For example, an item might be returned directly to the available stock, or sent for refurbishment. The ATG
Control Center identifies these actions as returned item dispositions.
When processing the receipt of a returned item, the agent selects a returned item disposition from a list that
can be customized. The disposition selected by the agent is stored with the record of the returned item in the
system.
Returned item dispositions are configured by performing the following steps:
1. Add a returnItemDisposition item to the /atg/commerce/custsvc/
CSRRepository. For example, the following will add a return reason of “incorrect size”:
<add-item item-descriptor=" returnItemDisposition"
repository="/atg/commerce/custsvc/CsrRepository">
<set-property name="description" value="incorrectSize"/>
<set-property name="updateInventory" value="false"/>
</add-item>
2. To add a new disposition code, copy all of the existing reason codes from the
atg.commerce.csr.returns.ReturnDispositionMessages.
properties file to a new properties file. Then add any new disposition codes to this file. The newly created
resource file should be set in the resourceBundle attribute. Continuing with the incorrect size example:
#atg.commerce.csr.returns.ReturnDispositionMessages.properties
incorrectSize=Incorrect Size
3. You can specify a new resource bundle by changing the resource bundle specified in the CSRRepository
definition file:
<item-descriptor name="returnItemDisposition">
<property name="readableDescription">
<attribute name="resourceBundle" value="com.example.MyResourceBundle"/>
</property>
</item-descriptor>
Creating Returned Item Dispositions
Use the ATG Control Center to create returned item dispositions:
1. Using the ATG Control Center, select the Customer Service task area from the main menu.
2. Select Returned Item Dispositions from the Customer Service submenu.
The system displays the Returned Item Dispositions screen. Click List to display all existing returned item
dispositions.
48 5 Configuring ATG Commerce Service Center
3. Click New Item to display the New Item dialog box. Type a description for the returned item disposition in the
Description field, for example, Return to Stock.
The description for the returned item disposition is displayed in the Action Taken with Returned Item drop-
down list on the Receive Returned Item page. An agent can select the returned item disposition when
processing the return of an item from a customer.
4. Click the Update Inventory field and then select True or False from the drop-down list. Selecting True will
increase the stock level of the item by the quantity that is returned. Selecting False will not increase the stock
level.
For example, if the given returned item disposition is Return to Stock, select True to have the item returned
to stock. However, if the returned item disposition is Item is Broken, selecting False, will not return the item to
stock and the inventory for the item will remain unchanged.
5. Optionally, enter an ID (or code) for the returned item disposition in the New ID field. If this field is left blank
the system will automatically generate an ID.
6. Click OK. The system creates the returned item disposition and displays it in the list on the Returned Item
Dispositions screen.
Configuring Oracle for Catalog Searching
If you are configuring your system to perform catalog searches against Oracle, you must perform the following:
1. Configure your Oracle ConText settings to index the columns that the catalog search queries.
2. You can also set the simulateTextSearchQueries of your Product Catalog to TRUE.
Note: When running on a production environment, do not set the simulateTextSearchQueries to TRUE,
as it will affect performance.
5 Configuring ATG Commerce Service Center 49
3. Add a new index:
create index
dcs_prd_chldsku_sid_idx on dcs_prd_chldsku (sku_id) indextype is
ctxsys.context;
This is needed because the following SQL is generated when searching by SKU:
SELECT DISTINCT t1.product_id,t1.product_type
FROM dcs_product t1, dcs_prd_chldsku t2, dcs_prd_catalogs t3
WHERE t2.product_id=t1.product_id
AND t3.product_id=t1.product_id
AND (CONTAINS(t2.sku_id,'xsku1126',0) > 1
AND t3.catalog_id = 'masterCatalog')
If you are not using custom catalogs, atg/commerce/custsvc/catalog/
ProductSearch.allowEmptySearch must be set to FALSE.
Setting up Scheduled Orders
Scheduled Orders is a feature of ATG Commerce for setting up automated recurring orders. For additional
information on scheduled orders, refer to the ATG Commerce Programming Guide.
A scheduled order is comprised of a template order and a schedule. A template order contains all of the order
information but is not submitted. The template can be associated with one or many schedules. Based on the
schedule(s) associated with the template, the template object is cloned to create an order object, which is then
submitted.
Agents can create scheduled order templates using the new order checkout process, or by copying an existing
order. Scheduled orders can be reviewed from the customer’s profile. Agents can also display all schedules for a
specific template, and submit an ad hoc order from a scheduled order.
Agents set up scheduled orders based on a daily, weekly, or monthly schedule. The schedule may be periodic,
which is based on an interval of time between each scheduled run, or calendar-based, which is based on specific
day to run. For periodic schedules, CSC allows an agent to choose intervals based on a number of days or
weeks. For calendar-based schedules, CSC allows an agent to specify days of the week or dates of the month. A
schedule also defines a start end date, which can be used to limit the period of time that the schedule is active.
Enabling and Disabling Scheduled Orders
Scheduled orders are enabled by default. To disable the scheduled orders feature, modify the
CSRConfigurator component, setting usingScheduledOrders to false.
For example, to disable scheduled orders:
$class=atg.commerce.csr.util.CSRConfiguratorscope=globalusingScheduledOrders=false
50 5 Configuring ATG Commerce Service Center
The usingScheduledOrders option controls the availability of the scheduling options at the end of checkout,
the scheduled orders panel on the Profile View screen and the scheduled order view screen for template orders.
Configuring Price Lists
Note: If your site uses price lists, you must configure the use of price lists as outlined in Defining the Default
Price List (page 85) later in this document.
The following section describes configuration that affects the pricing of scheduled orders when using price lists
in combination with scheduled orders. This configuration affects the pricing of scheduled orders when:
• Pricing a new scheduled order for submission
This occurs in ATG Commerce via the ScheduledOrderService and ScheduledOrderTools components
when scheduled orders are automatically created and submitted based on their pre-defined schedules.
• Pricing a scheduled order template for view in CSC
Scheduled order templates are priced whenever an agent selects one for viewing on the scheduled order
view. This ensures that the agent always views the current day pricing when looking at a scheduled order
template. The result of this pricing operation is not saved to the repository, and is only temporary for the view.
• Pricing a new scheduled order instance when the “Submit Now” feature is used in CSC
The Submit Now feature is used by an agent to manually create and submit and order from a scheduled order
template.
ScheduledOrderTools
This ATG Commerce component automatically generates and submits scheduled orders based on their
pre-defined schedules and contains configuration specific to the pricing of the scheduled orders they have
submitted.
The property useOrderPriceListsFirst controls how ScheduledOrderTools determines the correct
price lists to use. Set by default to false, the price list assignment is determined by looking at the price
lists assigned to the customer profile that owns the scheduled order. Because price list assignments are an
optional feature in ATG Commerce, if price list assignments are not implemented, the price list will come from
the PriceListManager default configuration of defaultPriceList and defaultSalesPricelist. For
additional information on ATG Commerce price lists, refer to the UsingPriceLists section of the ATG Commerce
Programming Guide.
If ScheduledOrderTools.isUseOrderPriceListsFirst is set to true, it will first attempt to get the
price lists by extracting them from the template. Pricing information must be stored with the scheduled
order template when it is created to be able to extract price lists from order templates. It may not be possible
to extract both price lists from the template. If the items in the order are all on sale, the list price cannot be
determined. Conversely, if no items are on sale, the sales price list cannot be determined. If the price list
cannot be determined from the template, the price list assignment is obtained from the customer profile that
owns the scheduled order. If price list assignments are not implemented, the price list will come from the
PriceListManager default configuration of defaultPriceList and defaultSalesPricelist.
It is important to note that there are situations that may occur when using either of these methods:
• When a site changes customer price list assignments based on store front selection, it is possible for an agent
to set up a scheduled order based on the current assignments for a customer. If the customer switches store
fronts, any new scheduled orders will be priced using the new assignments.
5 Configuring ATG Commerce Service Center 51
• If the price list on a customer’s profile is updated, and CSC has been configured to obtain price lists from the
order items first, the change will not be applied to any scheduled orders.
For information on customizing scheduled orders, refer to Customizing Scheduled Orders (page 68)
Using Scenarios
You can use scenarios to configure actions that are taken when internal users perform various tasks. Scenarios
are also used to configure events that are available to external users, such as cross-sells or promotions. For
general information on creating and working with scenarios, refer to the ATG Personalization Guide for Business
Users. For information on scenarios used with ATG Commerce, refer to the Using Commerce Elements in Scenarios
chapter of the ATG Commerce Guide to Setting Up a Store.
Configuring Scenario Events
When you use the ACC scenario editor on an ATG instance running Commerce Service Center, the scenarios you
create are internal scenarios they respond to actions performed by internal users such as agents, not external
users such as customers.
ATG Commerce Service Center includes a number of scenario events that can be triggered by agent activities.
You can incorporate these events in internal scenarios that you create.
The following table lists the scenario events included with ATG Commerce Service Center:
Event display name Triggered when . . .
Agent adds item to order Agent adds an item to an order
Agent adds payment group Agent adds a payment group to an order
Agent adds shipping group Agent adds a shipping group to an order
Agent cancels order Agent cancels an order
Agent changes item quantity Agent changes an item’s quantity
Agent claims item Agent claims a coupon, gift certificate, or store credit
Agent create order Agent creates a new order
Agent creates an order comment Agent creates a new order comment
Agent edits payment group Agent edits a payment group
Agent edits shipping group Agent edits a shipping group
Agent exchanges order Agent exchanges an order
Agent issues store credit Agent issues a store credit to a customer
52 5 Configuring ATG Commerce Service Center
Event display name Triggered when . . .
Agent overrides a price Agent overrides the price of a shipping group or commerce item
Agent receives a return item Agent receives an item that has been returned
Agent removes item from order Agent removes an item from an order
Agent returns order Agent returns an order
Agent splits a shipping group Agent splits a shipping group’s commerce items between shipping
groups
Agent submits order Agent submits an order
Agent views credit card Agent views a credit card
Agent views order Agent views an order
Agent views order payment Agent views an order’s payment information
Agent views order returns Agent views order return information
CSC Reporting Framework
The reporting framework used by CSC is similar to the framework used by ATG Commerce. CSC gathers log files
that contains order and agent information and loads it into the warehouse. For information on setting up and
configuring the ATG Commerce reporting framework, refer to the Preparing to Use Commerce Reporting section
in the ATG Commerce Programming Guide.
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.
5 Configuring ATG Commerce Service Center 53
The ReturnEventListener file is configured as follows:
$class=atg.commerce.reporting.ReturnEventListenerenabled^=/atg/dynamo/service/DWDataCollectionConfig.enableddataListeners=ReturnLogEntryQueueSinkreturnOrderJMSType=atg.commerce.csr.ReturnOrderexchangeOrderJMSType=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.DataCollectorQueuedataListeners=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.ReturnLogEntryGeneratordataListeners=ReturnFileLoggerenabled^=/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 filelogFileName=csc_return_# Rotate log files automatically every 1 hourschedule=every 1 hour# Or rotate when there are 10,000 records in the filedataItemThreshold=10000# The directory to place all the log data filesdefaultRoot^=/atg/dynamo/service/DWDataCollectionConfig.defaultRoot# The centralized Dynamo schedulerscheduler=/atg/dynamo/service/Scheduler# Add a timestamp to all the names of the log filestimestampLogFileName=true# Use this extension after the timestamplogFileExtension=.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.returnRequestIdenabled^=/atg/dynamo/service/DWDataCollectionConfig.enabled# Add a Unique ID to all the names of the log filesUIDLogFileName=true# IdGenerator
54 5 Configuring ATG Commerce Service Center
idGenerator=/atg/dynamo/service/IdGenerator# The JMS message typelogRotationMessageType=atg.reporting.ReturnOrder# The messageSource component to send log rotation messagemessageSource=/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 (page 25) 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 filelogFileName=svc_end_call_# Rotate log files automatically every 1 hourschedule=every 1 hour#Or rotate when there are 10,000 records in the filedataItemThreshold=10000# The directory to place all the log data filesdefaultRoot^=/atg/dynamo/service/DWDataCollectionConfig.defaultRoot# The centralized Dynamo schedulerscheduler=/atg/dynamo/service/Scheduler# Add a timestamp to all the names of the log filestimestampLogFileName=true# Use this extension after the timestamplogFileExtension=.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,
5 Configuring ATG Commerce Service Center 55
customerId, agentIdenabled^=/atg/dynamo/service/DWDataCollectionConfig.enabled# Add a Unique ID to all the names of the log filesUIDLogFileName=true# IdGeneratoridGenerator=/atg/dynamo/service/IdGenerator# The JMS message typelogRotationMessageType=atg.reporting.svc.Call# The messageSource component to send log rotation messagemessageSource=/atg/dynamo/service/LogRotationMessageSource
Loader Pipeline Overview
Loading the return item into a transactional fact table is a process that requires a number of stages to obtain and
work with the data in different ways. To clarify this process, it is presented as a data flow in which data flows from
one processor to the next. Along the way the data is transformed until the final processor records the data into
the transactional fact table.
Data loading starts with the implementation of the Loader. The atg.reporting.datawarehouse.
loader.Loader.Loader component uses the queueName property to point to a log file. The Loader runs
using a scheduler, creates a log file reader for returned items and invokes the processReader method of the
PipelineDriver component.
The PipelineDriver reads delimited lines from the log file then parses them and populates a pipeline
parameter. The parameter is then sent down a pipeline chain. The atg.reporting.datawarehouse.
loader.FilePipelineDriver.PipelineDriver component uses the properties paramPropertyNames and
paramClasses properties to specify the names and types of parameters that are read.
The PipelineManager runs the pipeline chain described in the pipeline.xml file. Pipelines consist of several
processors. These processors collect data, prepare line items and insert them in into the data warehouse.
Returns and Exchanges Pipeline Processors
The following processors are used in the Submit Return pipeline:
Pipeline Chain Pipeline Link Description
fetchReturn
/atg/reporting/datawarehouse/
processes/custsvc/FetchReturnProcessor
$class=atg.reporting.datawarehouse.
commerce.csr.FetchReturnProcessor
Uses the return ID to look up
the return/exchange in the CSR
repository.
returnRequestLookup
atg/reporting/datawarehouse/process/
custsvc/ReturnRequestLookupProcessor
$class=atg.reporting.datawarehouse.
process.LookupPipelineProcessor
This processor fetches all return
items in the warehouse for the
current return ID. If there are
return items the parameter
map entry is created for the
resultPropertyName value.
56 5 Configuring ATG Commerce Service Center
Pipeline Chain Pipeline Link Description
checkReturnExists
/atg/reporting/datawarehouse/process/
WarehouseItemExistsProcessor
$class=atg.reporting.datawarehouse.
process.WarehouseItemExistsProcessor
This processor allows a switch to
be implemented in the pipeline
by determining if a warehouse
item exists in the properties. If a
warehouseItemPropertyName
value exists in the parameter
map and the current log record
does not need to be processed. If
the map entry does not exist the
pipeline will process the next link.
createReturnLineItems
/atg/reporting/datawarehouse/process/
custsvc/CreateReturnLineItemsProcessor
$class=atg.reporting.datawarehouse.
commerce.csr.CreateLineItemsProcessor
This processor creates an array or
the returned items map.
allocateOtherRefund
/atg/reporting/datawarehouse/process/
custsvc/OtherRefundAllocatorProcessor
.properties
$class=atg.reporting.datawarehouse.
commerce.AmountAllocatorProcessor
This processor gets
refund information from
returnRequest.
actualOtherRefund and
then distributes the refund
amount based on return item
refund amount or quantity. The
ItemRefundLineItemAlocator
looks at the return item refund
subtotal. If the subtotal is greater
than zero, then it distributes the
amount based on the item refund
amount.
allocateReturnFee
/atg/reporting/datawarehouse/process/
custsvc/ReturnFeeAllocatorProcessor.
properties
$class=atg.reporting.datawarehouse.
commerce.AmountAllocatorProcessor
This processor gets the return fee
from returnRequest.
returnFee and uses the
ItemRefundLineItemAlocator
to distribute the return fee across
all return items.
calculateTotalAdjustments
/atg/reporting/datawarehouse/process/
custsvc/LineItemTotalAdjustments
Processor
$class=atg.reporting.datawarehouse.
commerce.ComputerLineItemTotal
Processor
This process sums up all
adjustments for each returned
item, such as shipping share,
tax share, and other return fee
allocation amounts. The suggested
shares are used to calculate the
actual share. If the suggested
share is zero, the share will be
calculated based on the return
item’s quantity.
5 Configuring ATG Commerce Service Center 57
Pipeline Chain Pipeline Link Description
calculateTotal
/atg/reporting/datawarehouse/process/
custsvc/LineItemTotalRefundProcessor
$class=atg.reporting.datawarehouse.
commerce.ComputerLineItemTotal
Processor
This processor sums up all total
adjustments and item refund
items.
localCurrencyLookup
/atg/reporting/datawarehouse/process/
custsvc/LocalCurrencyLookupProcessor
$class=atg.reporting.datawarehouse.
commerce.CurrencyConverterProcessor
This processor converts local
currency to standard currency
values.
CurrencyConverter
/atg/reporting/datawarehouse/process/
custsvc/CurrencyConverterProcessor
$class=atg.reporting.datawarehouse.
commerce.CurrencyConverterProcessor
This processor converts shipping,
tax and other refunds, the return
fee, total adjustments and refunds.
dayLookup
/atg/reporting/datawarehouse/process/
custsvc/DayLookupPipelineProcessor
$class=atg.reporting.datawarehouse.
process.DayLookupProcessor
This processor looks for the ID of
the day for a given time stamp.
This processor uses the return
request createdDate property to
return the ID.
timeLookup
/atg/reporting/datawarehouse/process/
custsvc/TimeLookupPipelineProcessor
$class=atg.reporting.datawarehouse.
process.TimeLookupProcessor
This processor looks for the ID of
the time for a given time stamp.
This processor uses the return
request createdDate property to
return the ID.
customerLookup
/atg/reporting/datawarehouse/process/
custsvc/CustomerLookupProcessor
$class=atg.reporting.datawarehouse.
process.RepositoryItemLookupProcessor
$scope=global
This processor gets the customer
ID from the returnRequest.
order.profileId. If the
customer is not found in the data
warehouse, it will look in the
production schema. If found in
neither schemas, the processor will
return Unspecified.
58 5 Configuring ATG Commerce Service Center
Pipeline Chain Pipeline Link Description
agentLookup
/atg/reporting/datawarehouse/process/
custsvc/InternalUserLookupProcessor
$class=atg.reporting.datawarehouse.
process.InternalUserLookupProcessor
$scope=global
This processor gets the agent ID
from the returnRequest.
agent.repositoryId. If the
agent is not found in the data
warehouse, it will look in the
production schema. If found in
neither schemas, the processor will
return Unspecified.
returnSalesChannelLookup
/atg/reporting/datawarehouse/process/
custsvc/ReturnSalesChannelLookup
Processor
$class=atg.reporting.datawarehouse.
process.EnumeratedPropertyLookup
Processor
This processor looks up the return
channel ID in the data warehouse.
runReturnLineItemPipelineChain
/atg/reporting/datawarehouse/process/
custsvc/ReturnItemPipelineProcessor
This processor runs the return item
pipeline for each element of the
LineItems array.
returnItem lookupReturnSku
/atg/reporting/datawarehouse/process/
custsvc/SkuLookupProcessor
$class=atg.reporting.datawarehouse.
process.LookupPipelineProcessor
This processor looks up the SKU
ID for each return item in the data
warehouse.
lookupReturnProduct
/atg/reporting/datawarehouse/process/
custsvc/ProductLookupProcessor
$class=atg.reporting.datawarehouse.
process.LookupPipelineProcessor
This processor looks up the
product ID for each return item in
the data warehouse.
lookupReturnReason
/atg/reporting/datawarehouse/process/
custsvc/ReturnReasonLookupProcessor
$class=atg.reporting.datawarehouse.
process.LookupPipelineProcessor
This processor looks up the return
reason ID for each return item in
the data warehouse.
5 Configuring ATG Commerce Service Center 59
Pipeline Chain Pipeline Link Description
logReturnItem
/atg/reporting/datawarehouse/process/
custsvc/ReturnItemLoggerProcessor
$class=atg.reporting.datawarehouse.
process.RepositoryLoggerProcessor
This processor creates a repository
item for the logged data that is
based upon the lookup properties.
Calls Pipeline Processors
The following processors are used in the call pipeline:
Pipeline Chain Pipeline Link Description
calls callLookup
/atg/reporting/datawarehouse/process
/svc/CallLookupProcessor.properties
$class=atg.reporting.datawarehouse.
process.LookupPipelineProcessor
This processor obtains the
call item for the call ID. If the
call item exists, the parameter
map entry is created for the
resultPropertyName.
checkCallExists
/atg/reporting/datawarehouse/process/
WarehouseItemExistsProcessor
$class=atg.reporting.datawarehouse.
process.WarehouseItemExistsProcessor
This processor implements
a switch in the pipeline by
determining if a warehouse
item exists in the properties. If a
warehouseItemPropertyName
value exists in the parameter map,
the current log record does not
need to be processed. If the map
entry does not exist, the pipeline
will process the next link.
customerLookup
/atg/reporting/datawarehouse/process/
custsvc/CustomerLookupProcessor
$class=atg.reporting.datawarehouse.
process.RepositoryItemLookupProcessor
$scope=global
This processor gets the customer
ID from the parameter map. If
the customer is not found in the
data warehouse, it will look in the
production schema. If found in
neither schemas, the processor
will return Unspecified.
agentLookup
/atg/reporting/datawarehouse/process/
custsvc/InternalUserLookupProcessor
$class=atg.reporting.datawarehouse.
process.InternalUserLookupProcessor
$scope=global
This processor gets the agent ID
from the parameter map. If the
agent is not found in the data
warehouse, it will look in the
production schema. If found in
neither schemas, the processor
will return Unspecified.
60 5 Configuring ATG Commerce Service Center
Pipeline Chain Pipeline Link Description
dayLookup
/atg/reporting/datawarehouse/process/
custsvc/DayLookupPipelineProcessor
$class=atg.reporting.datawarehouse.
process.DayLookupProcessor
This processor looks for the
start time timestamp from the
parameter map as well as the
lookup for the day of the time
stamp.
timeLookup
/atg/reporting/datawarehouse/process/
custsvc/TimeLookupPipelineProcessor
$class=atg.reporting.datawarehouse.
process.TimeLookupProcessor
This processor looks for the
start time timestamp from the
parameter map as well as the
lookup for the time of the time
stamp.
enddayLookup
/atg/reporting/datawarehouse/process/
custsvc/DayLookupPipelineProcessor
$class=atg.reporting.datawarehouse.
process.DayLookupProcessor
This processor looks for the
end time timestamp from the
parameter map as well as the
lookup for the end day of the time
stamp.
endtimeLookup
/atg/reporting/datawarehouse/process/
custsvc/TimeLookupPipelineProcessor
$class=atg.reporting.datawarehouse.
process.TimeLookupProcessor
This processor looks for the
end time timestamp from the
parameter map as well as the
lookup for the end time of the
time stamp.
totalTime This processor calculates the total
amount of call time in seconds.
callLogger
$class=atg.reporting.datawarehouse.
process.RepositoryLoggerProcessor
This processor creates a repository
item for the logged data based on
the lookup properties.
6 Setting Up Access Control 61
6 Setting Up Access Control
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.
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,
see Installing and Configuring ATG Commerce Service Center (page 9).
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:
• Tab Security - Security for the Commerce Service Center tab accessed through the Service Framework tabs
• Panel Security - Security for a panel
• 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
62 6 Setting Up Access Control
For more information about access rights, see the ATG Personalization Programming Guide
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:
• csrTicketing - Includes the access rights necessary to use the Ticketing UI
• 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
• 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
• 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, refer toAppendix B, CSC Access
Rights Comparison (page 169).
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.
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.
For additional information on creating roles, refer to the ATG Business Control Center User’s Guide.
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:
6 Setting Up Access Control 63
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.
64 6 Setting Up Access Control
7 Customizing ATG Commerce Service Center 65
7 Customizing ATG Commerce Service
Center
Depending on the requirements of your site, you may need to modify some of the default behavior of the
Commerce Service Center. Much of this behavior is determined by the properties of Nucleus components, so
you can customize your system through configuration of these properties using the ACC. For more extensive
changes, you may want to extend ATG Commerce Service Center classes and create new components from your
classes.
Using the CSRConfigurator Component
The /atg/commerce/custsvc/util/CSRConfigurator component configures ATG Commerce settings,
through the following properties:
Property Name Description
catalogTools Specifies the CatalogTools component to use. Default is
/atg/commerce/catalog
/CatalogTools.
maximumAlmostQualifiedFor
PromotionsInShortList
The number of promotion closeness qualifiers to display on
the shopping cart. The default number is set to 6.
quantityInputTagMaxLength The maximum number of characters that the quantity
input field will accept. The default number is set to 10.
quantityInputTagSize The display size of the quantity input field. If the
quantityInputTagMaxLength size is set to 10, yet the
quantityInputTagSize is set to 5, the user will be able
to enter 10 characters, but only 5 of the 10 characters will
be displayed. The default number is set to 10.
processReturnRequestImmediately If set to true, then the return request process will begin
immediately.
66 7 Customizing ATG Commerce Service Center
Property Name Description
usingPriceLists If set to true, indicates that the running commerce
application uses price lists.
defaultCatalogId Specifies the catalog to use for anonymous shopping (only
if using custom catalogs).
Customizing E-Mail
You can configure how ATG Commerce Service Center manages customer profiles.
Note: These components are modified using the ACC.
Configuring E-mail Notifications
When an agent creates a new customer profile, a password is automatically generated for the customer’s
account, and an e-mail notification is typically sent to the customer’s e-mail address. The /atg/svc/agent/
UI/Formhandlers/CustomerProfileFormHandler component has several properties for managing new
account e-mail notifications:
Property Name Description
sendNewAccountEmails If true, an e-mail containing the new account login
and password is generated and sent to the customer.
Default is true.
persistNewAccountEmails If true, new account e-mails are persisted in the
customer’s profile before they are sent. Default is
false.
newAccountTemplateEmailInfo The atg/svc/email/ component creates the e-mail
message.
sendNewAccountEmailInSeparateThread If it is a new account, e-mail is sent in a separate
thread. The default is true.
For information about configuring a TemplateEmailInfo component, see the ATG Personalization
Programming Guide.
New Password Configuration
When an agent generates a new password for a customer in the Commerce Service Center, the customer’s
profile must have a valid e-mail address so the new password can be e-mailed to the /atg/svc/agent/UI/
7 Customizing ATG Commerce Service Center 67
Formhandlers/CustomerProfileFormHandler component has several properties for managing e-mail
notifications:
Property Name Description
sendResetPasswordEmails If true, an e-mail containing the new password is
generated and sent to the customer. Default is true.
resetPasswordtemplateEmailInfo The resetPasswordTemplateEmailInfo
component that creates the e-mail message. Default
is ForgotEmailTemplateInfo (in /atg/svc/
email/).
sendResetPasswordEmailInSeparateThread If true, the reset password e-mail is sent in a
separate thread. The default is true.
For information about configuring a TemplateEmailInfo component, see the ATG Personalization
Programming Guide.
Configuring Order Confirmation E-Mails
It is possible to configure e-mail confirmations that occur once an order has been placed. The /atg/commerce/
custsvc/util/CSRAgentTools allow you to configure order confirmation e-mails.
Property Name Description
confirmationEmailMap
NEW_ORDER /atg/commerce/custsvc/profile/NewOrderEmailInfo
ORDER_UPDATE /atg/commerce/custsvc/profile/OrderUpdateEmailInfo
ORDER_EXCHANGE /atg/commerce/custsvc/profile/OrderExchangeEmailInfo
ORDER_RETURN /atg/commerce/custsvc/profile/OrderReturnEmailInfo
A new e-mail information component can be associated with any of the keys to override the default e-mail
component.
Configuring E-Mail Templates
E-mail confirmations are sent for the following activities. CSC provides a default email template implementation
for each of these:
• New Account Registration
68 7 Customizing ATG Commerce Service Center
• New Account Registration Following Checkout
• Password Reset
• New Order Confirmation
• Order Modification Confirmation
• Return Confirmation
• Exchange Confirmation
The e-mail information component can be reconfigured to use a different templateURL property, which points
to a different JSP page specifying a different template.
To change an e-mail template, set the templateURL property of any of the following TemplateEmailInfo
components:
• /atg/svc/email/NewAccountTemplateEmailInfo
• /atg/commerce/custsvc/profile/NewAccountEmailInfo
• /atg/svc/email/ResetPasswordTemplateEmailInfo
• /atg/commerce/custsvc/profile/NewOrderEmailInfo
• /atg/commerce/custsvc/profile/OrderExchangeEmailInfo
• /atg/commerce/custsvc/profile/OrderReturnEmailInfo
• /atg/commerce/custsvc/profile/OrderUpdateEmailInfo
Customizing Scheduled Orders
Once you have enabled your site to use scheduled orders as outlined in Enabling and Disabling Scheduled
Orders (page 49), the following customizations can be made. For additional information on customization of
scheduled orders, refer to the ATG Commerce Programming Guide.
The CSRScheduledOrderFormHandler creates two variables, the CalendarSchedule variable used
for specific days, and the PeriodicSchedule that is used for interval schedules. Additionally, the
CSRScheduledOrderFormHandleris responsible for creating and updating the scheduled order repository
item based on the input provided from the agent.
In addition to these two schedule types, CSC provides an additional N number of intervals option used
with PeriodicSchedule that an agent can use to limit the number of scheduled intervals. This schedule option
automatically calculates the schedule’s end date by calculating the schedule’s nextRunTimen number of times
starting from the specified start time.
Note: The number of intervals is used only to calculate the end date and will not be available when a schedule is
viewed or updated.
CSRScheduledOrderFormHandler contains the following configurable values for controlling the default
selections on the schedule creation form.
7 Customizing ATG Commerce Service Center 69
Property Description
defaultScheduleType Identifies the default schedule type. Possible values are Calendar or
Interval
defaultDaysOption Controls which CalendarSchedule day selection is the default.
Possible values are allDays, selectedDays, or selectedDates
defaultMonthsOption Controls which CalendarSchedule month selection is the default.
Possible values are allMonths or selectedMonths
defaultEndDateOption Controls which Schedule end date option is the default. Possible
values are none, endBy or endAfterOccurrences
defaultOccurrencesOption Controls which CalendarSchedule occurrences option
is the default. Possible values are allOcurrences or
selectedOccurrences
defaultInterval Controls the default interval for an PeriodicSchedule
defaultIntervalOption Controls the default interval option for PeriodicSchedules.
Possible values are days or weeks
Displaying Scheduling Information
CSC provides an extension to the core ATG Commerce CSRScheduledOrderInfoScheduledOrderInfo servlet
bean that provides additional output parameters that describe the contents of the schedule. Refer to the ATG
Commerce Programming Guide for information on ScheduledOrderInfo.
CSCScheduledOrderInfo has the following additional output parameters:
• readableDays
• readableDates
• readableHours
• readableMinutes
• readableMonths
• readableOccurrences
• readableMonths
Scheduled Order Components
The following components are used for scheduled orders:
Class Description
Component: /atg/commerce/custsvc/order/scheduled/CSRScheduledOrderTools
70 7 Customizing ATG Commerce Service Center
Class Description
atg.commerce.csr.order.scheduled.
CSRScheduledOrderTools
Contains various helper APIs
Component:
/atg/commerce/custsvc/order/scheduled/CSRScheduledOrderFormHandler
atg.commerce.csr.order.scheduled.
CSRScheduledOrderFormHandler
Form handler used to create and update
schedules
Component: /atg/commerce/custsvc/order/scheduled/DuplicateAndSubmit
atg.commerce.csr.order.scheduled.
DuplicateAndSubmit
Form handler used by the Submit Now feature
Component: /atg/commerce/custsvc/order/scheduled/IsScheduledOrder
atg.commerce.csr.order.scheduled.
IsScheduledOrder
Servlet bean used to determine if an order is a
scheduled order template
Component: /atg/commerce/custsvc/order/scheduled/ScheduledOrderTableFormHandler
atg.commerce.csr.order.scheduled.
ScheduledOrderTableFormHandler
Form handler used to generate the content
displayed in the customer’s scheduled orders
panel
Component:
/atg/commerce/custsvc/order/scheduled/SchedulesTableFormHandler
atg.commerce.csr.order.scheduled.
SchedulesTableFormHandler
Form handler used to generate the content
displayed in the scheduled order view’s
schedules panel
Component: /atg/commerce/custsvc/order/scheduled/SubmittedOrdersTableFormHandler
atg.commerce.csr.order.scheduled.
SubmittedOrdersTableFormHandler
Form handler used to generate the content
displayed in the scheduled order view’s
submitted orders panel
Component: /atg/commerce/custsvc/order/scheduled/ActivateSchedule
atg.commerce.csr.order.scheduled.
LoadAndExecuteAction
Form handler used to active a schedule from the
schedule order view
Component: /atg/commerce/custsvc/order/scheduled/DeactivateSchedule
atg.commerce.csr.order.scheduled.
LoadAndExecuteAction
Form handler used to deactivate a schedule from
the schedule order view
7 Customizing ATG Commerce Service Center 71
Scheduled Orders Pipeline Additions
The following are additions to the commercepipeline.xml that defines various purchase process pipelines
used by CSC.
Pipeline Chain Description
initScheduledOrderEdit This chain is executed by the CloneEditManager to prepare for updating
a previously created scheduled order template.
reconcileScheduledOrder This chain is executed by the CloneEditManager to reconcile changes
made to a previously created scheduled order template.
processTemplateOrder This chain is executed by the CSRCommitOrderFormHandler when the
Schedule option is used at the end of new order checkout. It validates that
a new order is ready to be saved as a scheduled order template.
Modifying Submitted Orders
ATG Commerce Service Center allows the modification of submitted orders that have not been fulfilled, as well
as returns and exchanges to orders that have been fulfilled.
To identify what orders can be returned, edit the modifiable and returnable-order states:
1. Configure which order states are not modifiable using the following component:
# /atg/commerce/custsvc/order/OrderIsModifiable
nonModifiableOrderStates=REMOVED,
QUOTED,
NO_PENDING_ACTION,
PENDING_REMOVE,
PENDING_CUSTOMER_RETURN
nonModifiablePaymentGroupStates=REMOVED,
SETTLED
2. Configure which order states are returnable using the following component:
# /atg/commerce/custsvc/order/OrderIsReturnable
shippingGroupShippedStates=NO_PENDING_ACTION
When an agent modifies an order, the order’s state determines how the edit process is handled. CSC can stage
changes to an order and then apply them all in a single commit action.
The process of modifying submitted orders uses a cloning technique where the order is cloned into a duplicate
order. After the order is cloned, all modifications are applied to the clone order and then reconciled with the
original order in a single commit transaction.
The cloning technique is performed on selected orders based on their state. The isCloneEditState(Order)
API determines if a particular order qualifies for this process. This API, by default, returns a result based on
72 7 Customizing ATG Commerce Service Center
the clonedEditOrderState configured in CSRAgentTools. The configured states include: SUBMITTED,
PROCESSING, PENDING_MERCHANT_ACTION and TEMPLATE.
Additional states can be added by modifying the configuration of CSRAgentTools clone edit order states or by
extending the isCloneEditState API.
When the order has been cloned for modification, the application is in clone edit mode. When an agent is
working on a clone order there will be no indication in the UI. The UI will always show the original order
ID. The isCloneEditMode() API in the CSROrderHolder determines when this mode is active. The
getOriginalOrder() API is used for returning the original order ID when required.
Cloning Pipelines
The entire cloning process is facilitated by a pair of pipelines or chains. One chain prepares the order for editing
by creating the clone copy. Another chain reconciles the changes with the original order when everything is
committed by the agent.
These two chains are executed based on the state of the order. For example, different chains could be defined
for handling orders in different states. CSC provides one set of chains for handling all orders is a submitted
state as defined by the submitted order states configured in CSRAgentTools. These two chains can be modified
using standard configuration override techniques.
The CloneEditManager component contains the configuration for mapping order states to the chain names
using properties named initializeEditChains and reconcileOrderChains.
The following describes each link in the two chains.
Chain: initSubmittedOrderEdit - executed at the start of the edit process
Link Processor Component Description
cloneOrderForEdit /atg/commerce/custsvc/
order/edit/processor/
CloneOrderForEdit
Performs the cloning of the order
at the repository level and creates
the Commerce objects from the
newly created order item by calling
loadOrder.
validateCloneForEdit /atg/commerce/custsvc/
order/edit/processor/
ValidateCloneFor
Edit
Validates the clone order after it has
been created.
initializeCloneEditState /atg/commerce/custsvc/
order/edit/processor/
InitializeClone
EditState
Initializes a state object based on
the two orders, which is used to
later reconcile the changes back to
the original order.
Chain: reconcileSubmittedOrder - execute to reconcile the changes with the original order
initializeReconcilitation /atg/commerce/custsvc/order/
edit/processor/
InitializeReconciliation
Prepares the state object
for reconciliation.
7 Customizing ATG Commerce Service Center 73
applyChanges /atg/commerce/custsvc/order/
edit/processor/ApplyChanges
Copies the changes to the
original order based on
the contents of the clone
order and information
stored in the clone edit
state object created in
the initialization pipeline.
executeValidate
OriginalOrder
/atg/commerce/order/processor/
ExecuteValidateFor
CheckoutChain
Executes the core
commerce process that
validates the original
order for checkout.
removeEmptyShippingGroups
FromOriginal
/atg/commerce/order/processor/
RemoveEmptyShippingGroups
Executes the core
commerce process that
removes empty shipping
groups from the original
order.
removeEmptyPaymentGroups
FromOriginal
/atg/commerce/order/processor/
RemoveEmptyPaymentGroups
Executes the core
commerce process that
removes empty payment
groups from the original
order.
createImplicitRelationships
ForOriginal
/atg/commerce/order/processor/
CreateImplicitRelationships
Executes the core
commerce process
that creates implied
relationships between
commerce objects in the
original order.
setPaymentGroupAmounts
OnOriginal
/atg/commerce/order/processor/
SetPaymentGroupAmount
Executes the core
commerce process
sets the amount of the
payment groups based
on relationship in the
original order.
authorizePaymentGroups /atg/commerce/custsvc/order/
edit/processor/
AuthorizePaymentGroups
Executes a process that
adjusts for the authorized
amounts of the payment
groups in the original.
(e.g. new payment groups
are authorized and
changed payment groups
have their authorized
amounts adjusted.
updateOriginalOrder /atg/commerce/order/processor/
UpdateOrder
Calls updateOrder on
the original order.
74 7 Customizing ATG Commerce Service Center
reconcileGiftlistRepository /atg/commerce/custsvc/order/
edit/processor/
ReconcileGiftListRepository
Reconciles gift list
quantities for changes
made to the original
order.
consumePromotions /atg/commerce/custsvc/order/
edit/processor/
ConsumePromotions
Consumes coupon
promotions that may
have been claimed and
used during the edit
process.
sendCouponPromotion
UsedMessages
/atg/commerce/custsvc/order/
edit/processor/SendCoupon
PromotionUsedMessages
Sends the core commerce
PromotionUsed JMS
event for each consumed
promotion identified by
the previous processor.
sendFulfillment
Notifications
/atg/commerce/custsvc/order/
edit/processor/Send
FulfillmentNotifications
Sends fulfillment JMS
events for each change
applied to the original
order.
sendAgentEvents /atg/commerce/custsvc/order/
edit/processor/
SendAgentEvents
Sends agent audit events
for each change made to
the original order.
Cloning Core Classes
The following describes a few of the core classes and components that implement the clone edit feature and are
the likely places for applications to apply overrides and extensions:
CloneEditManager
This class provides some of the core configurations to the feature. It provides the API for executing the pipeline
chains and performing call backs to the CloneEditHandlers throughout the entire process.
Classes atg.commerce.order.edit.CloneEditManager
Subclass atg.commerce.csr.order.edit.CSRCloneEditManager
Component /atg/commerce/custsvc/order/edit/CSRCloneEditManager
Configuration cloneEditHandlers provide a list of CloneEditHandler components
intializeEditChains is a map of pipeline chains used in the initialization process.
Keyed by order state.
reconcileOrderChains is a map of pipeline chains used in the initialization process.
Keyed by order state.
7 Customizing ATG Commerce Service Center 75
CloneEditHandler
This abstract class is used for creating application classes that participate in the entire process through a callback
interface. Components of this type are configured in the CloneEditManager and are executed at various points
in the initialization and reconciliation processes.
Classes atg.commerce.order.edit.CloneEditHandler
Subclass atg.commerce.csr.order.edit.CollectionEditHandler,
CommerceItemEditHandler, PaymentGroupEditHandler,
ShippingGroupEditHandler, ManualAdjustmentEditHandler,
RelationshipEditHandler, HandlingInstructionEditHandler,
AgentCommerceEditHandler, MarkerEditHandler, OrderPropertyEditHandler
Component /atg/commerce/custsvc/order/edit/OrderPropertyHandler
/atg/commerce/custsvc/order/edit/CommerceItemHandler
/atg/commerce/custsvc/order/edit/ShippingGroupHandler
/atg/commerce/custsvc/order/edit/HandlingInstructionHandler
/atg/commerce/custsvc/order/edit/PaymentGroupHandler
/atg/commerce/custsvc/order/edit/RelationshipHandler
/atg/commerce/custsvc/order/edit/ManualAdjustmentHandler
/atg/commerce/custsvc/order/edit/AgentCommentHandler
/atg/commerce/custsvc/order/edit/MarkerHandler
CloneEditState
This class defines the state object used by the clone edit process. It provides access to the original and clone
orders and API for adding and retrieving state information. It is created and returned by the initialization process
and is required as input to the reconciliation process.
Classes atg.commerce.order.edit.CloneEditState
ATG Commerce Service Center stores this object in the window scoped CSROrderHolder, which can be
accessed using the getCloneEditState API.
CSROrderHolder
This class defines the shopping cart used by an agent to modifying customer orders. It provides an API for
determining when the application is in clone edit mode, storing the clone edit state object and for masking the
current working order id with the original order id. The loadOrder(Order) API initiates the clone edit process
for a given order and stores the clone edit state object.
Classes atg.commerce.csr.order.CSROrderHolder
Components /atg/commerce/custsvc/order/ShoppingCart
76 7 Customizing ATG Commerce Service Center
CSRAgentTools
This class provides the more generic API used by the application. This includes the configuration for submitted
order states and the API for determining if an order should used the cloning feature.
Classes atg.commerce.csr.util.CSRAgentTools
Components /atg/commerce/custsvc/util/CSRAgentTools
CSRCommitOrderFormHandler
This form handler class provides the handlers for triggering the reconciliation process.
Classes atg.commerce.csr.order.CSRCommitOrderFormHandler
Components /atg/commerce/custsvc/order/CSRCommitOrderFormHandler
Extending Core Commerce Objects for Cloning
You may extend core Commerce objects, for example: Order, ShippingGroup, PaymentGroup, Relationship.
A site might have extended OrderImpl into MyStoreOrderImpl to add new properties, or added a new type
of payment group called MyStoresPaymentMethod. The configuration of the clone editing components may
need adjusting or, in some cases, class extensions may be necessary.
It may be necessary to change the cloning process when an application has added new properties to the core
Commerce objects. Under normal circumstances all repository items referenced by the cloned item are also
cloned into new transient repository items. This is known as the deep clone. An application may want new
properties cloned or may want to eliminate certain properties from the cloning process.
The cloning feature allows you to configure the cloning process to exclude certain properties in the deep clone
process in the atg/commerce/custsvc/order/edit/processor/CloneOrderForEdit component. The
excludedOrderProperties component maps order repository item types to a list of properties that should be
excluded from the deep cloning process. The following is the default configuration that disables the repository
cloning for properties of two types in the order repository:
excludedOrderProperties= itemPriceInfo=priceList, pricingAdjustment=pricingModel
An application can also introduce a custom CloneEditHandler to perform special handling on their
application specific properties. For example, an application may want to exclude custom property from the
deep clone and handle the cloning process another way. The CloneEditHandler callback interface is executed
after the repository cloning process is completed and provides an opportunity for applications to execute post
cloning logic.
If an application has extended the core Commerce objects, the new types must be identified to the clone editing
feature. During the reconciliation phase, cloned object properties are copied to their original order counterpart.
7 Customizing ATG Commerce Service Center 77
You must map which properties should be copied based on the type of object. The following is an example of
the configuration for the OrderImpl object type.
Component: atg/commerce/custsvc/order/edit/OrderPropertyHandlerpropertiesToCopyOnUpdate=\atg.commerce.order.OrderImpl=description,,state,,stateDetail,,taxPriceInfo,,priceInfo,,specialInstructionsTo add MyStoreOrderImpl:propertiesToCopyOnUpdate+=\myapp.commerce.order.MyAppOrderImpl=myCustomProperty
Note: Only the extended properties of the class must be defined for each class extension.
The same type of configuration change is needed for extensions to the CommerceItem, ShippingGroup,
PaymentGroup and Relationship objects. See CommerceItemHandler, ShippingGroupHandler,
PaymentGroupHandler and RelationshipHandler respectively.
Handling and Fulfillment
If a site uses the ATG Fulfillment module, when an order is originally submitted, the order and some of its
contained objects will change state once the notification is received by the fulfillment subsystem.
Note: If running the ATG Fulfillment module, it must be run in the Agent cluster.
Object State after submit State after received by fulfillment
Order Submitted to
Fulfillment
Processing
ShippingGroup Initial Pending shipment
ShippingGroupRelationship Initial Pending delivery
A pipeline is executed to reconcile the changes with the original order. At the end of this chain there is a link that
triggers the fulfillment notification messages. This process creates and sends the fulfillment Modification objects
for changes made to the original order.
When the submitted order is modified by the Agent in the UI, new shipping groups and relationships may be
created as a result. In this case, the new shipping groups and shipping group relationships will be saved in
their Initial state. An application must extend the reconciliation process to perform any state modifications
to these objects (e.g. to mark them in their pending shipment and pending delivery states). This could be
accomplished by either extending the reconciliation pipeline chain or responding the modification fulfillment
events generated by the process.
For additional information on handling and fulfillment, refer to the ATG Commerce Programming Guide.
Fulfillment Notification for Order Modifications
CSC sends standard fulfillment notification messages for all changes made to the order. They are sent out in the
form of the following ATG Core Commerce objects:
78 7 Customizing ATG Commerce Service Center
atg.commerce.fulfillment.PaymentGroupUpdateatg.commerce.fulfillment.ShippingGroupUpdateatg.commerce.fulfillment.GenericAddatg.commerce.fulfillment.GenericRemove
CSC uses the ATG Commerce OrderFulfillmentTools API to create these objects. For example, when a new
payment group is added, CSC calls the following OrderFulfillmentTools API to generate the modification
object.
createGenericAddValueToValueModification(Modification.TARGET_PAYMENT_GROUP, pPaymentGroup, Modification.TARGET_ORDER, pOrder);
For new commerce items, shipping groups and payment groups CSC sends GenericAdd messages. For updated
commerce items, shipping groups and payment groups, CSC sends GenericUpdate, ShippingGroupUpdate
and PaymentGroupUpdate objects respectively. Commerce items are the only objects for which CSC sends
GenericRemove events. For updates made to other Order properties, CSC generates GenericUpdate events.
All the events are generated by the clone edit handlers during the reconciliation process that occurs when an
agent commits his updates from the order review page.
CSC Pricing Overview
The following section outlines how pricing is performed in CSC and describes the components and API that can
be used or modified to change pricing behavior.
Loading Orders and Pricing
CSC prices all modifiable orders when they are first loaded into the current global context, or selected by the
agent. However, not all orders are priced the same. The CSREnvironmentMonitor component is responsible
for pricing an order that has been selected in the current global context. The entire order is priced using
PricingConstants.OP_REPRICE_ORDER_TOTAL as the pricing operation. This is not configurable.
Which order are modifiable by CSC is configurable and determined by the state of the order. Both incomplete
and submitted orders are considered modifiable. Incomplete and submitted are conditions that are also
determined by the state of the order and can be configured in CSC. CSRAgentTools contains API and
configurable properties for determining which orders are considered modifiable, incomplete, and submitted.
The configurable properties in /atg/commerce/custsvc/util/CSRAgentTools are:
incompleteOrderStates^=/atg/commerce/order/OrderLookupService. incompleteStatessubmittedOrderStates=SUBMITTED,PROCESSING,PENDING_MERCHANT_ACTION#both nonModifiableOrderStates and nonModifiablePaymentGroupStates areused to determine a non-modifable order.
nonModifiableOrderStates=REMOVED,\
7 Customizing ATG Commerce Service Center 79
QUOTED,\ NO_PENDING_ACTION,\ PENDING_REMOVE,\ PENDING_CUSTOMER_RETURN
nonModifiablePaymentGroupStates^=\/atg/commerce/order/PaymentGroupManager.nonModifiablePaymentGroupStates
Return Value API
The following API determines the return value by comparing the order’s current state to the configured values.
These could be extended to perform more robust logic that cannot be determined by state alone:
CSRAgentTools.isOrderSubmitted(Order pOrder)CSRAgentTools.isOrderIncomplete(Order pOrder)CSRAgentTools.isOrderModifiable(Oreer pOrder)
Submitted Orders and Clone Editing
When an agent selects an order that is considered modifiable, CSC will make a copy of that order when it
is considered to be in a clone edit state. Refer to the Modifying Submitted Orders (page 71) section for
additional information on cloning.
Because the order is copied into a transient state for the edit process, the changes applied by initial pricing
operation on the order are not immediately saved to the repository. They are only saved if the agent completes
the post-submit checkout of the order.
Price Lists and Pricing
When pricing is obtained using global context price list selections, CSC takes advantage of a core commerce
feature that allows the price lists to be passed into the pricing engine to override the core behavior that uses
the active profile’s assigned price list. The list price list and sale price list can be specified in an extra parameter
map that is passed to the pricing operation API. The pricing engine uses these price lists in place of the profile’s
assigned price list. The list price list and sale price list that are loaded in the global context are passed in to the
pricing engine using the extra parameter map.
The following core Commerce PricingTools API is used for pricing orders. Note the Map parameter that is
included on the API:
public OrderPriceInfo priceOrderTotal(Order pOrder, PricingModelHolder pPricingModels, Locale pLocale, RepositoryItem pProfile, Map pExtraParameters)
The CSRAgentTools API generates a Map that contains the ids of the current global context price list selections.
This API is used by CSC to generate the extra parameter map for pricing operations. CSC has also extended
createRepriceParameterMap of all the PurchaseProcessFormHandlers to call this API:
80 7 Customizing ATG Commerce Service Center
public Map addPriceListParameter(Map pExtraParameters)
The CSRAgentTools API is used for pricing an order that will call addPriceListParameter as part of the
process:
public void repriceOrder(String pRepricingOperation, Order pOrder, PricingModelHolder pUserPricingModels, Locale pLocale, RepositoryItem pCustomerProfile, RepositoryItem pAgentProfile,Map pExtraParameters, PipelineErrorHandler pErrorHandler)
CSREnvironmentTools contains the API for accessing the global context price list selections, setting new
global context price list selections and extracting a price list from an order:
public RepositoryItem getCurrentPriceList()public RepositoryItem getCurrentSalePriceList()public void setCurrentPriceList(RepositoryItem pPriceList)public void setCurrentSalePriceList(RepositoryItem pPriceList)public RepositoryItem getListPriceListFromOrder(Order pOrder)public RepositoryItem getSaleListPriceListFromOrder(Order pOrder)
Automatic Removal of Items
If CSC is configured to use price lists, it will automatically remove items from the order that cannot be priced
by the current global context price list. This avoids pricing errors when the order is first loaded. When loading
an order into global context, CSC attempts to determine the correct price lists (list price list and sale price list)
to use by extracting them the order being loaded. This helps eliminate the problem of removing items from an
order because an incorrect price list is in global context when the order is loaded. CSC automatically changes
the global context price list selections to match those found in the order.
Promotions
CSC defines two PricingModelHolders for pricing orders. CSC decides which one to use based on the state of
the order and each holder is initialized with promotions differently.
• atg/commerce/custsvc/pricing/CustomerPricingModels --this holder is used when pricing
incomplete orders. It is initialized with the active customer’s current promotions.
• atg/commerce/custsvc/pricing/SubmittedOrderPricingModels--this holder is used when pricing
submitted orders. It is initialized with the order’s applied promotions.
Incomplete orders or schedule order templates
CSC uses the active customer’s current promotions when pricing incomplete (e.g. orders not submitted) orders.
Submitted orders
For orders that have already been submitted to fulfillment, CSC uses the promotions that were originally applied
to the order when it was submitted.
7 Customizing ATG Commerce Service Center 81
Note that this is not the same as the promotions that were available at the time the order was submitted. It only
includes the promotions that were applied to the order when it was submitted. For example, if a buy-two-get-
one-free promotion was available when the order was submitted but only one was purchased and therefore
not applied to the order, that promotion will not be in the SubmittedOrderPricingModels when the order is
modified after submission to add the second item.
API for Determining the Correct PricingModelHolder
CSREnvironmentTools contains an API that returns the correct pricing model holder for the order
currently loaded into the global context. CSREnvironmentMonitor and all of the CSC extensions to the
PurchaseProcessFormHandler call this API to determine the correct pricing model holder for pricing
operations.
public PricingModelHolder getCurrentOrderPricingModelHolder
Scheduled Order Templates
CSC always uses the CustomerPricingModels PricingModelHolder for pricing order templates. Scheduled
order templates are priced this way to provide the agent with pricing information that reflects the current day
pricing. This gives the agent an accurate representation of the order total if an order were to be submitted from
the template on that day.
Modifying scheduled order templates also uses clone editing and therefore, pricing changes are not saved to the
template unless the post create checkout process is completed for the template.
Scheduled Order Templates are also unique because they are priced before being viewed by an agent. For
example, if an agent views the contents of a template in read-only mode before actually selecting the template
to work on, the view would reflect current day pricing for the template. However, any pricing changes made
for viewing the template are not persisted to the repository; they are only performed to provide the agent with
current day pricing in the view.
Manual Pricing Adjustments
It is possible to adjust an order total by a fixed amount. Adjustments can either be a fixed increase (debit) or
decrease (credit) to the order total. The details of a manual adjustment such as the amount, adjustment type and
reason code are permanently stored within the database. Any manual adjustments that exist for an order at the
time the order is priced will always be applied. For information on the corresponding ATG Commerce API, refer
to the ATG Commerce Programming Guide.
All manual adjustments are created as transient repository items. Subsequent processing in the updateOrder
pipeline determines if the adjustments is permanently added to the repository based on the following rules.
• All adjustments created for submitted orders are unconditionally persisted to the repository. As configured by
default, this is the only time ATG Commerce and CSC unconditionally saves adjustments to the repository.
• All adjustments created for persistent, incomplete orders are conditionally saved based on configuration. CSC
uses a Boolean configuration setting, whose default value is false, that determines if adjustments should be
saved immediately for persistent, incomplete orders.
The Commerce updateOrder pipeline contains a processor that saves the manual adjustment items to the
repository when appropriate. saveManualAdjustment executes the atg/commerce/order/
processor/SaveManualAdjustments processor with the following two processor configurations:
82 7 Customizing ATG Commerce Service Center
## The processor will save the manual adjustments to the repository for# orders in these states, depending on the value of saveIncomplete# saveForIncompleteOrders#incompleteStates^=/atg/commerce/order/OrderLookupService.incompleteStates## The processor will save the manual adjustments to the repository for# orders in the configured incomplete states if this property is true.# Otherwise, the manual adjustments are not saved for incomplete orders.#saveIncompleteOrderAdjustments=false
Important: Be aware of a condition that may occur when saving incomplete manual adjustments. Manual
adjustments are, by default, applied unconditionally. Once added to the order, manual adjustments affect the
order’s price despite the contents of the order. This is important if an incomplete order is saved with manual
adjustments as subsequent changes to the order at checkout time will not change any adjustments that have
been applied. For example, if an agent applies a $20 credit adjustment to an order with $100 merchandise and
saves it in an incomplete state, the customer could return and remove $80 worth of merchandise from the order
and checkout with a $0 total. As such, the processor is configured by default to not save manual adjustments for
incomplete orders.
The OrderAdjustmentCalculator adjusts the order’s subtotal based on the manual adjustments associated
with the order. The /atg/commerce/pricing/calculators/
OrderAdjustmentCalculator component contains the following configuration:
$class=atg.commerce.pricing.OrderAdjustmentCalculatorpricingTools=/atg/commerce/pricing/PricingTools
The adjustment calculator is added as a postCalculator in the /atg/commerce/pricing/
OrderPricingEngine. As such, the calculator runs after the pre-calculators and all calculators associated with
any promotions for the order. The configuration for the OrderPricingEngine is:
postCalculators+=\ calculators/OrderAdjustmentCalculator
For additional information on pricing and calculators, refer to the ATG Commerce Programming Guide.
Configuring Catalog and Price Lists
ATG Commerce Service Center contains two global environment objects used by the application to manage
catalogs and orders: current catalog and current price list. The current settings of these objects can be viewed
and changed in the Commerce tab submenu.
The current catalog and price list used are specified in the agent’s profile. The catalog and price list
are initialized using information from the current customer. When the agent logs in, the current
catalog and price list are initialized based on the CSRConfigurator.defaultCatalogId and
PriceListManager.defaultPriceList settings. However, when the agent selects a new customer, the
current catalog and price list settings automatically adjust to whatever has been assigned to the customer.
7 Customizing ATG Commerce Service Center 83
Using the Current Catalog
The current catalog is only used when custom catalogs are employed by the application. It determines which
catalog is used by the agent when browsing and searching the catalog.
The value of the current catalog can be set by the following actions:
• When the agent first logs in, a new, transient profile is automatically loaded as the active customer. The
current catalog is set from the new profile’s assigned catalog. If the profile does not have an assigned catalog,
the current catalog is set based on the CSRConfiguratordefaultCatalogId property.
• When the agent selects a customer from the profile repository to be the active customer, the current catalog
is set based on the selected profile’s assigned catalog.
• The agent can manually select a different catalog using the UI. Once an agent has explicitly selected a catalog,
that catalog remains active even if a new customer with a different assigned catalog is selected from the
repository. Starting a new call will reset the current catalog and remove the agent’s explicitly selected catalog.
Using the Current Price List
The current price list is only used when the price lists are employed. It determines which price list is used for
catalog and order pricing operations. It is also used to determine the pricing locale.
The CSRConfigurtor has a property called usingPriceLists, which must be set to true when the
application is using price lists.
The values of the current price list can be set by the following actions:
• When the agent first logs in, a new, transient profile is automatically loaded as the active customer. The
current price list is set from the new profile’s assigned price list. If the profile doesn’t have an assigned price
list, the current price list is set based on the PriceListManagerdefaultPriceList.
• When the agent selects a customer from the profile repository to be the active customer, the current price list
is set based on the selected profile’s assigned price list.
• When the agent selects an order from the repository to be the active order, the current price list is set based
on the first commerce item in the order with a price list assigned. A commerce item’s price info contains a
reference to the price list used to the price it.
• The agent can manually select a different price list using the UI. Once an agent has explicitly selected a price
list, that price list remains active even if a new customer with a different assigned price list is selected from the
repository. Starting a new call will also reset the current price list and remove the agent’s explicitly selected
price list.
CSREnvironmentTools
Class atg.commerce.csr.environment.CSREnvironmentTools
Component /atg/commerce/custsvc/environment/CSREnvironmentTools
This component contains the API for gaining access to the current catalog and current price list
84 7 Customizing ATG Commerce Service Center
CSRAgentTools
Class atg.commerce.csr.util.CSRAgentTools
Component /atg/commerce/custsvc/util/CSRAgentTools
This component contains the API for generating a parameter map for pricing operations that contains the active
price list.
ChangeCatalogAndPricelist
Class atg.svc.agent.environment.EnvironmentChangeFormHandler
Component /atg/commerce/custsvc/environment/ChangeCatalogAndPricelist
This form handler component is used to manually change the catalog and price list through the UI.
Quick Access Catalogs and Price Lists
Quick access catalogs and price lists are available as sub navigational menus from the catalog and price list
menus, allowing quick access the most commonly used catalogs and price lists.
Quick access catalogs and price lists are configured by creating SiteOption items in the /atg/svc/option/
OptionRepository and specifying the catalog or price list IDs of the catalogs or price lists that should appear
in the quick-access menus. The defaultValue property specifies a list of catalog or price list IDs for the catalogs
or price lists to display.
The following is an example of a quick-access catalog site:
<add-item item-descriptor="SiteOption" id="QuickAccessCatalogs"> <set-property name="name" value="QuickAccessCatalogs"/> <set-property name="accessRight" value="serviceAdminDefaultRight"/> <set-property name="multiValued" value="true"/> <set-property name="dataType" value="String"/> <set-property name="defaultValue" value="catalog10002,masterCatalog"/> </add-item>
The following is an example of a quick-access price list site:
<add-item item-descriptor="SiteOption" id="QuickAccessPriceLists"> <set-property name="name" value="QuickAccessPriceLists"/> <set-property name="accessRight" value="serviceAdminDefaultRight"/> <set-property name="multiValued" value="true"/> <set-property name="dataType" value="String"/> <set-property name="defaultValue" value="listPrices,plist20003,salePrices"/> </add-item>
7 Customizing ATG Commerce Service Center 85
Defining the Default Custom Catalog
If your site uses custom catalogs, the catalog is derived from the catalog assigned in the profile. If there
is not catalog assigned, the defaultCatalogId property of the /atg/commerce/custsvc/util/
CSRConfigurator component specifies the catalog to use for anonymous shoppers.
Defining the Default Price List
If your site uses price lists, you must configure the following:
• The /atg/commerce/custsvc/util/CSRConfigurator component property usingPriceLists must be
set to true. This enables the use of price lists.
• Each customer must be assigned a price list. The defaultPriceListId property of the /atg/commerce/
pricing/pricelists/PriceListManager component specifies the price list to use for anonymous
shoppers.
Setting the Pricing Locale
The active customer pricing locale drives the currency and currency codes of prices used in CSC. The active
pricing locale may be customized based on the supported currencies of the store.
Class atg.commerce.csr.util.CSRAgentTools
Component /atg/commerce/custsvc/util/CSRAgentTools
The getActiveCustomerPricingLocale() method provides access to the pricing locale and will return the
price list locale (if one is specified and price lists are being used). If the price list locale is unavailable, the locale
stored in the customer profile will be used. Failing that, if /atg/commerce/custsvc/util/
CSRAgentTools.useRequestLocale=true, the current request locale will be used. If all of these attributes are
unavailable, the value of the /atg/commerce/pricing/PricingTools.defaultLocale will be used.
Enabling Custom Catalogs
When using custom catalogs (the DCS.CustomCatalogs module), you must modify the /atg/
userprofiling/internalUserProfile.xml file. By default, the property attribute is commented
out. Extend the internalUserProfile.xml file by copying the file to /atg/userprofiling/
internalUserProfile.xml in your localconfig directory and uncomment the catalog property.
1. Ensure that the following code is in the /atg/userprofiling/
internalUserProfile.xml file in your localconfig directory. Uncomment the catalog property
definition:
<item-descriptor name="agent">
<!--uncomment property if running custom catalog -->
<property name="catalog" property-type="atg.repository.nucleus.
NucleusReferencePropertyDescriptor" data-type="atg.repository.
RepositoryItem">
<attribute name="component" value="/atg/commerce/custsvc/
86 7 Customizing ATG Commerce Service Center
environment/CSREnvironmentTools"/>
<attribute name="property" value="currentCatalog"/>
<attribute name="scope" value="global"/>
<attribute name="repositoryName" value="/atg/commerce/catalog/
ProductCatalog"/>
<attribute name="itemTypeName" value="catalog"/>
<attribute name="typeName" value="string"/>
</property>
</item-descriptor>
2. To configure the default catalog for anonymous shoppers, set the defaultCatalogId property of the /atg/
commerce/custsvc/util/
CSRConfigurator component to the ID of the default catalog.
Customizing Shipping and Payment Group Types
CSC supports, by default, two shipping group types: Hard Goods and Electronic Shipping. CSC also supports, by
default, three payment group types: Gift Certificate, Credit Card and Store Credit Payment Group.
You can customize shipping groups and payment groups to do things such as add custom fields or add support
for a new shipping group type. For additional information on working with shipping and payment groups, refer
to the ATG Commerce Programming Guide.
Shipping and Payment Group Configuration Overview
Shipping and payment group configuration is defined using the atg.commerce.csr.order.
CommerceTypeConfiguration class. The class contains the following:
protected PageFragment mAddPageFragment;protected PageFragment mEditPageFragment;protected PageFragment mDisplayPageFragment;protected PageFragment mImagePageFragment;protected String mResourceBundle;protected String mType;protected String mAddPageFragmentTitleKey;protected String mEditPageFragmentTitleKey;protected String mImageHoverTextKey;
The CommerceTypeConfiguration class uses the following properties:
Property Description
AddPageFragment Adds a specific shipping or payment group type.
EditPageFragment Edits a specific shipping or payment group type.
DisplayPageFragment Displays a specific shipping or payment group type.
7 Customizing ATG Commerce Service Center 87
Property Description
ImagePageFragment Displays an image used with a specific shipping or payment group type.
ResourceBundle The configuration used to obtain the resourced values.
Type The primary key used to identify the shipping or payment group type
configuration. The key is used as a map key for the system-generated
shipping or payment group configuration map, which locates the
configuration type.
AddPageFragmentTitleKey Defines the text used in the AddPageFragment title.
EditPageFragmentTitleKey Defines the text used in the EditPageFragment title.
ImageHoverTextKey Defines the text displayed when a user hovers over the image defined in
the ImagePageFragment.
Default Shipping Group Types
ATG provides two default shipping group types: hard goods and electronic goods. Shipping group types
are configured using the atg.commerce.csr.order.CommerceTypeConfiguration class. The following
information describes how to reconfigure the default shipping group types or to configure new types.
The shipping group configuration files and the shipping group page fragment configuration files are available at
the following locations:
File Location
Configuration File <ATG9dir>/CSC9.4/DCS-CSR/config/atg/commerce/custsvc/ui/
Page Fragments <ATG9dir>/CSC9.4/DCS-CSR/config/atg/commerce/custsvc/ui/
fragments/order/
Display JSPs <ATG9dir>/CSC9.4/web-apps/DCS-CSR/include/order/
Add and Edit JSPs <ATG9dir>/CSC9.4/web-apps/DCS-CSR/panels/order/shipping/
Display Page Fragments
To change how your shipping groups are displayed, you must modify the displayPageFragment property
page fragment file. Each shipping group type defines three display values that appear on various pages. A
display value consists of a title and content and is configured in the display page fragment JSP file, where they
are identified in the file as value1, value2 and status.
You can customize the default display values for the existing shipping group types. However, if you create new
shipping group types, each new shipping group type must have a defined set of display values.
The following display values are configured for the hard good shipping type:
88 7 Customizing ATG Commerce Service Center
Value Title Content Example
Value1 Shipping Address [first] [last]
[address 1]
[address 2]
[city], [state] [zip code]
[country]
[phone number]
Bob Smith
119 Grand Street
Apt. 1509
Brooklyn, NY 10023
USA
212-555-4321
Value2 Shipping Method [shipping method] Ground
Status Status [shipping group status] Ready to Ship
The following display details are configured for the electronic shipping group type:
Value Title Content Example
Value1 Electronic Address [email address] [email protected]
Value2 Blank [blank] Blank
Status Status [shipping group status] Emailed
Display details are used on the following pages for both shipping group types, unless otherwise indicated:
Display Location Value1 Value2 Status
Shipping Addresses Page
Shipping Method Page (hard good only)
X
Order Review Page
Return Items Page
Confirmation Emails
X X
Order View Page
Scheduled Orders Page
X X X
The /atg/commerce/custsvc/ui/HardGoodShippingGroupConfiguration.properties and
ElectronicGoodShippingGroupConfiguration.properties files hold all of the properties of the page
fragments. The following is an example of the HardGoodShippingGroupConfiguration.
properties file:
$class=atg.commerce.csr.order.CommerceTypeConfiguration
addPageFragment=/atg/commerce/custsvc/ui/fragments/order/
7 Customizing ATG Commerce Service Center 89
AddHardgoodShippingGroupeditPageFragment=/atg/commerce/custsvc/ui/fragments/order/ EditHardgoodShippingGroupdisplayPageFragment=/atg/commerce/custsvc/ui/fragments/order/ DisplayHardgoodShippingGroupimagePageFragment=/atg/commerce/custsvc/ui/fragments/order/ HardgoodShippingGroupImagetype=hardgoodShippingGroupaddPageFragmentTitleKey=addHardgoodShippingGroupTitleeditPageFragmentTitleKey=editHardgoodShippingGroupTitleimageHoverTextKey=hardgoodShippingGroupImageHoverTextresourceBundle=atg.commerce.csr.order.WebAppResources
The DisplayHardgoodShippingGroupConfiguration.properties file identifies the location of your page
fragment JSP file and the servletContext. For example:
$class=atg.web.PageFragment
URL=/include/order/displayHardgoodShippingGroup.jspservletContext=DCS-CSR
The displayHardgoodShippingGroup.jsp file contains the values for the display details, including the title
and the content. You must modify the value1, value2 and status properties with your custom information.
The combination of these parameters defines one display value, such as value1:
• displayValue - This optional parameter is used to display the value of the desired field
• displayHeading - This optional parameter is used to display the heading of the desired field
Example: Shipping Group Display Page Fragment Components
The following is a portion of the default configuration of the displayhardgoodShippingGroup.jsp file. In
this example, the displayHeading parameter, which defines the display value1 title, is set to use the Shipping
Address header. The displayValue parameter, which defines the display value1 content, is set to use the
addressView.jsp fragment:
<c:if test="${propertyName == 'value1'}"> <c:if test="${displayHeading == true}"> <fmt:message key="shipping.address.header"/> </c:if> <c:if test="${displayValue == true}"> <dsp:include src="/include/addresses/addressView.jsp" otherContext="${csrConfigurator.contextRoot}"> <dsp:param name="address" value="${address}"/> </dsp:include> </c:if>
To display your customized shipping group title and content, modify the displayHeading and
displayValues accordingly. For example, in the displayElectronicShippingGroup.jsp file, the value1
title has been modified to define the displayHeading as Electronic Address and the displayValue as
emailAddress:
<c:if test="${propertyName == 'value1'}">
90 7 Customizing ATG Commerce Service Center
<c:if test="${displayHeading == true}"> <fmt:message key='shippingSummary.electronicAddress.header'/> </c:if> <c:if test="${displayValue == true}"> <li> <c:out value="${shippingGroup.emailAddress}"/> </li> </c:if></c:if>
As noted above, the title and content for value1 is shown on the Shipping Addresses, Shipping Method (hard
good only), Order Review, Return Items, Order View, Scheduled Orders pages and on confirmation emails. You
may also modify the value2 property as needed. Note that electronic shipping groups do not use the value2
property by default, so it is left blank. You may add the displayHeading and displayvalues to the property
as required.
Other components that can be customized within the display page fragment include the status property.
This property is used to identify the status of the group object and displayed only on the Order View and the
Scheduled Order pages. The default title for both the hard good and electronic shipping group is Status, and the
content defaults to shippingGroup.stateAsString. Modify the heading of the display value to point to your
customized information as needed:
<c:if test="${propertyName == 'status'}"> <c:if test="${displayHeading == true}"> <fmt:message key='shippingSummary.shippingStatus.header'/> </c:if> <c:if test="${displayValue == true}"> <dsp:droplet name="ShippingGroupStateDescriptions"> <dsp:param name="state" value="${shippingGroup.stateAsString}"/> <dsp:param name="elementName" value="stateDescription"/> <dsp:oparam name="output"> <dsp:droplet name="IsHighlightedState"> <dsp:param name="obj" value="${shippingGroup}"/> <dsp:oparam name="true"> <span class="atg_commerce_csr_dataHighlight"><dsp:valueof param="stateDescription"></dsp:valueof></span> </dsp:oparam> <dsp:oparam name="false"> <dsp:valueof param="stateDescription"></dsp:valueof> </dsp:oparam> </dsp:droplet> </dsp:oparam> </dsp:droplet> </c:if></c:if>
The selectOptionText property is used to identify the information that is presented in the address drop down
on the Ship to Multiple Addresses and Split Quantity pages. By setting the displayValue, you configure what
address information is presented in the drop down. For example, the default configuration for the hard good
shipping group contains the following:
<c:if test="${propertyName == 'selectOptionText'}"> <c:if test="${displayValue == true}"> ${fn:escapeXml(address.address1)}${!empty address.address2 ? ' ' : '' }${!empty address.address2 ? fn:escapeXml(address.address2) : '' } </c:if>
7 Customizing ATG Commerce Service Center 91
</c:if>
The electronic shipping group selectOptionText property has been modified to include the following:
<c:if test="${propertyName == 'selectOptionText'}"> <c:if test="${displayValue == true}"> ${fn:escapeXml (shippingGroup.emailAddress)} </c:if></c:if>
Modify the display value with your customized page fragment.
Customizing a Shipping Group Type
For additional information on creating customized Shipping Groups, refer to the Working with Purchase Process
Objects chapter of the ATG Commerce Programming Guide.
1. Refer to the Order Tools section of the ATG Commerce Programming Guide to create a new shipping group
type. This includes defining the type-to-class name mapping for ShippingGroup objects.
2. Refer to the Create a Shipping Group section of the ATG Commerce Programming Guide to create the shipping
group.
Note: If you do not want to initialize the custom shipping group types using the ShippinGroupDroplet,
continue on to step 6.
3. Write a new ShippingGroupInitializer implementation. The initializeShippingGroups() method
should gather the user’s ShippingGroups by type and add them to the ShippingGroupMapContainer
referenced by the ShippingGroupFormHandler.
4. Open your custom application and modify
ShippingGroupDroplet.propertiesshippingGroupInitializers parameter by adding your new
shipping group type. For example:
/atg/commerce/custsvc/order/ShippingGroupDroplet.properties
## ServiceMap of shippingGroupTypes to ShippingGroupInitializer
Nucleus components
shippingGroupInitializers+=\
newShippingGroup=/atg/commerce/custsvc/order/NewShippingGroupInitializer
5. Update the /atg/commerce/custsvc/util/CSRConfigurator.properties file
shippingGroupTypesToBeInitialized property and shippingGroupTypeConfigurations property to
include your new shipping group type.
This configuration initializes shipping group types in the ShippingGroupDroplet.
6. Initialize your new shipping group type by adding your new shipping group type to the
shippingGroupTypesToBeInitialized property. For example:
/atg/commerce/custsvc/util/CSRConfigurator.properties
## Shipping group fragment settings
shippingGroupTypesToBeInitialized= newShippingGroup
shippingGroupTypeConfigurations+=\ /atg/commerce/custsvc/ui/
NewShipingGroupConfiguration
92 7 Customizing ATG Commerce Service Center
7. Add the CommerceTypeConfiguration component to the shippingGroupTypeConfigurations
property for any new supported shipping group type.
Default Payment Group Types
Payment group type configuration is defined using the atg.commerce.csr.order.
PaymentGroupTypeConfiguration class. The class contains the following:
atg.commerce.csr.order.PaymentGroupTypeConfiguration extends atg.commerce.csr.order.CommerceTypeConfiguration protected PageFragment mEditRefundMethodPageFragment; protected PageFragment mDisplayRefundMethodPageFragment; mEditRefundMethodPageFragmentTitleKey;
The PaymentGroupTypeConfiguration class configures the payment group and refund methods. The base
class properties configure the payment group. The refund methods are used for the returns and exchange
pages.
The following payment group types are provided in these locations:
File Location
Configuration File <ATG9dir>/CSC9.4/DCS-CSR/config/atg/commerce/custsvc/ui/
Page Fragments <ATG9dir>/CSC9.4/DCS-CSR/config/atg/commerce/custsvc/ui/
fragments/order/
Display JSPs <ATG9dir>/CSC9.4/web-apps/DCS-CSR/include/order/
Add and Edit JSPs <ATG9dir>/CSC9.4/web-apps/DCS-CSR/panels/order/billing/
There are three default payment group types, including Credit Card, Store Credit and Gift Certificate.
To make customizations, you can modify the page fragments and override the component
or page fragment properties. Payment group information is displayed on a number of pages,
including the billing, order view, email and refund method pages. Payment group information
is displayed using the PaymengGroupTypeConfiguration.displayPageFragment and
PaymentGroupTypeConfiguration.displayRefundMethodPageFragment property values.
The following table provides display information on Credit Card type payment groups:
Value Title Content Example
Value1 Type [credit card type] – [last four
digits of card]
Visa - 2112
Value2 Expiration Date [card expiration year] / [card
expiration year]
11/12
7 Customizing ATG Commerce Service Center 93
Value Title Content Example
Value3 Billing Address [first] [last]
[address 1]
[address 2]
[city], [state] [zip code]
[country]
[phone number]
Bob Smith
119 Grand Street
Apt. 1509
Brooklyn, NY 10023
USA
212-555-4321
Status Status [payment group status] Authorization
succeeded
The following table provides display information on Store Credit type payment groups:
Value Title Content Example
Value1 Type Store Credit – Store Credit Number Store Credit – 1c1123
Value2 Amt. Remaining [store credit remaining] 15.32
Value3 Blank [blank] blank
Status Status [payment group status] Debited
The following table provides display information on Gift Certificate type payment groups:
Value Title Content Example
Value1 Type Gift Certificate – Gift
Certificate Number
Gift Certificate – 1g4332
Value2 Amt. Remaining [amount remaining] 15.32
Value3 Blank [blank] blank
Status Status [payment group status] Debited
The display values are used in the following locations:
94 7 Customizing ATG Commerce Service Center
Display Pages Value1 Value2 Value3 Status
Billing
Order Review
Refund Type
Confirmation Emails
X X X
Order View
Scheduled Orders
Refund Review
X X X X
The /atg/commerce/custsvc/ui/CreditCardConfiguration.properties,
StoreCreditConfiguration.properties and GiftCertificateConfiguration.properties files hold
all of the properties of the page fragments. The configuration file contains the page fragment location.
The following examples use the Credit Card payment group; however, all three payment group types have
corresponding files.
The following is an example of the CreditCardConfiguration.properties file:
$class=atg.commerce.csr.order.PaymentGroupTypeConfigurationaddPageFragment=/atg/commerce/custsvc/ui/fragments/order/AddCreditCardeditPageFragment=/atg/commerce/custsvc/ui/fragments/order/EditCreditCarddisplayPageFragment=/atg/commerce/custsvc/ui/fragments/order/ DisplayCreditCard
type=creditCardaddPageFragmentTitleKey=addCreditCardTitleeditPageFragmentTitleKey=editCreditCardTitleresourceBundle=atg.commerce.csr.order.WebAppResources
editRefundMethodPageFragment=/atg/commerce/custsvc/ui/fragments/order/ EditCreditCardRefundMethoddisplayRefundMethodPageFragment=/atg/commerce/custsvc/ui/fragments/order/ DisplayCreditCardRefundMethodeditRefundMethodPageFragmentTitleKey=editCreditCardRefundMethodTitle
The CreditCardConfiguration.properties file identifies the location of the page fragment, which in turn,
defines your page fragment JSP file and the servletContext. For example:
$class=atg.web.PageFragment
URL=/include/order/displayCreditCard.jspservletContext=DCS-CSR
The displayCreditCard.jsp file contains the values for the display details, including the title and the
content. You must modify the default value1, value2, value3 and status properties with your custom
information. The combination of these parameters defines one display value, such as value1:
• displayValue - This optional parameter is used to display the value of the desired field
• displayHeading - This optional parameter is used to display the heading of the desired field
7 Customizing ATG Commerce Service Center 95
Example: Payment Group Display Page Fragment Components
The following is a portion of the default configuration of the displayCreditCard.jsp file. In this example,
the displayHeading parameter, which defines the display value1 title, is set to use the Billing Summary
header. The displayValue parameter, which defines the display value1 content, is set to display the credit
card information:
<c:if test="${propertyName == 'value1'}"> <c:if test="${displayHeading == true}"> <fmt:message key='billingSummary.commerceItem.header.type'/> </c:if> <c:if test="${displayValue == true}"> <csr:displayCreditCardType creditCard="${paymentGroup}"/> </c:if></c:if>
To display your customized payment group title and content, modify the displayHeading and
displayValues accordingly. For example, in the GiftCertificate.jsp file, the value1 title has
been modified to use the same displayHeading but the displayValue has been modified to use the
newOrderBilling gift certificate value:
<c:if test="${propertyName == 'value1'}"> <c:if test="${displayHeading == true}"> <fmt:message key='billingSummary.commerceItem.header.type'/> </c:if> <c:if test="${displayValue == true}"> <fmt:message key="newOrderBilling.displayPaymentMethods.giftCertificate"/> <c:if test="${!empty paymentGroup && !empty paymentGroup.giftCertificateNumber }"> <fmt:message key="common.hyphen"/> <c:out value="${paymentGroup.giftCertificateNumber}"/> </c:if> </c:if></c:if>
As noted above, the title and content for value1 is shown on the Billing, Order Review, Refund Type, Order View,
Scheduled Orders and Refund Review pages and on confirmation emails. You may also modify the value2 and
value3 property as needed. Note that Store Credit and Gift Certificate payment groups do not use the value3
property by default, so it is left blank. You may add the displayHeading and displayvalues to the property
as required.
Other components that can be customized within the display page fragment include the status property. This
property is used to identify the status of the group object and is displayed only on the Order View, Scheduled
Orders and Refund Review pages. The default title for all payment groups is Status. Modify the display value to
point to your customized information as needed. The following is an example of the displayCreditCard.jsp
status:
<c:if test="${propertyName == 'status'}"> <c:if test="${displayHeading == true}"> <fmt:message key='billingSummary.commerceItem.header.state/> </c:if> <c:if test="${displayValue == true}"> <dsp:droplet name="PaymentGroupStateDescriptions">
96 7 Customizing ATG Commerce Service Center
<dsp:param name="state" value="${paymentGroup.stateAsString}"/> <dsp:param name="elementName" value="stateDescription"/> <dsp:oparam name="output"> <dsp:droplet name="IsHighlightedState"> <dsp:param name="obj" value="${paymentGroup}"/> <dsp:oparam name="true"> <span class="atg_commerce_csr_dataHighlight"><dsp:valueof param="stateDescription"></dsp:valueof></span> </dsp:oparam> <dsp:oparam name="false"> <dsp:valueof param="stateDescription"></dsp:valueof> </dsp:oparam> </dsp:droplet> </dsp:oparam> </dsp:droplet> </c:if></c:if>
Customizing a Custom Payment Group Type
For additional information on creating customized Payment Groups, refer to the Working with Purchase Process
Objects chapter of the ATG Commerce Programming Guide.
1. Refer to the Order Tools section of the ATG Commerce Programming Guide to create a new payment group
type. This includes defining the type-to-class name mapping for PaymentGroup objects.
2. Refer to the Extending the Payment Process to Support a New Payment Method section of the ATG Commerce
Programming Guide to create the payment group.
Note: If you do not want to initialize the customer payment group type using the PaymentGroupDroplet,
continue to Step 6.
3. Write a new PaymentGroupInitializer implementation. The initializePaymentGroups() method
should gather the user’s PaymentGroups by type and add them to the PaymentGroupMapContainer
referenced by the PaymentGroupFormHandler.
4. Within your custom application, create a new PaymentGroupInitializer implementation and add it to the
ServiceMap in the PaymentGroupDroplet.properties file paymentGroupInitializers property. For
example:
/atg/commerce/custsvc/order/PaymentGroupDroplet.properties
## ServiceMap of paymentGroupTypes to PaymentGroupInitializer
Nucleus components
paymentGroupInitializers+=\
newPayment=/atg/commerce/custsvc/order/NewPaymentInitializer
5. Update the /atg/commerce/custsvc/util/CSRConfigurator.properties file
paymentGroupTypesToBeInitialized and paymentGroupTypesConfigurations properties to include
your new payment group type.
This configuration initializes payment group types in the PaymentGroupDroplet. By default, this property
initializes the creditCard and storeCredit types. To initialize a new payment group type, add your new
payment group type to the paymentGroupTypesToBeInitialized property. For example:
/atg/commerce/custsvc/util/CSRConfigurator.properties
## Payment group fragment settings
paymentGroupTypesToBeInitialized=creditCard,storeCredit,newPayment
paymentGroupTypeConfigurations+=\
7 Customizing ATG Commerce Service Center 97
/atg/commerce/custsvc/ui/NewPaymentGroupConfiguration
6. Add the payment group type configuration to the CSRConfigurator:
atg.commerce.csr.util.CSRConfigurator
protected String mPaymentGroupTypesToBeInitialized;
protected CommerceTypeConfiguration[] mPaymentGroupTypeConfigurations;
protected Map mPaymentGroupTypeConfigurationsAsMap = null;
The following parameters are identified:
• type – This property is the primary key used to identify the payment group type configuration. This
property value should match the key defined in OrderTools.paymentTypeClassMap
• paymentGroupTypeConfigurationsAsMap – This property is automatically generated based on the
paymentGroupTypeConfigurations property values
• PaymentGroupTypeConfiguration.type – This property is used as the key for the map and the value is
the PaymentGroupTypeConfiguration componenet itself
Limiting Amounts for Payment Groups
When working on the Billing page an agent can enter any amount for a payment group. If the payment group is
associated with a claimable item, the agent will not be allowed to enter more than the remaining or maximum -
allowed amount.
You can limit the amount of your customized payment group types by extending the
CSRPaymentGroupRemainingAmount droplet to set the payment group maximum-allowed and remaining
amount limits.
The CSRPaymentGroupRemainingAmount droplet returns both the remaining and maximum-allowed amounts
for the payment group. This droplet sets a maximum -allowed amount limitation in the Billing page and displays
the remaining amount of the payment group on the Billing, Order View and Order Review pages.
This droplet takes in payment group and order as input parameters. The parameters for the
PaymentGroupRemainingAmount droplet are:
• paymentGroup – (Required) This parameter obtains the remaining and max allowed amount.
• order – (Optional) This parameter is added for custom extensions that may need to work with the order.
• remainingAmount - The remaining amount is calculated for the payment group and returned in this
parameter. The remaining amount is only calculated for store credit and gift certificates. This parameter
returns the PaymentGroup remaining amount that is backed by the claimable item.
• maxAllowedAmount – This parameter calculates and returns the maximum-allowed amount for the payment
group. This parameter is used only in the billing page.
You can calculate the remaining or maximum-allowed amounts for any custom payment groups by extending
the getRemainingAmount() and getMaxAllowedAmount() methods within the droplet.
Customizing Refund Methods
You can add support for new refund methods by performing the following steps:
98 7 Customizing ATG Commerce Service Center
1. Extend the atg.commerce.csr.returns.RefundMethod class, which holds your custom refund method
information. To create a limit of the refund amount for the custom refund method type, you must extend the
getMaximumRefundAmount() method. This method is used in the refundType page. The maximum refund
amount disables a user’s ability to enter a higher refund amount. If you do not implement the method, no
refund amount limit is set.
2. Extend the refundMethod repository item descriptor, which is defined in the /atg/commerce/custsvc/
CsrRepository.xml file. Extend the refundMethod item descriptor to save custom refund method
information in your database.
3. Extend the ReturnManager.buildRefundMethodList() method, which builds the list
of RefundMethod objects from the original order’s payment groups. This list is stored in the
returnRequest.getRefundMethodList(). It generates a RefundMethod for each credit card that has
any debited amount that has not yet been credited. If there is still a refund left over, the method allocates
the remainder to the generated store credit refund method. You must extend this method to add custom
RefundMethod objects but ensure that you do not allocate money across RefundMethods.
4. Extend the ReturnTools.createRefundMethodItem() method, which creates a refund method item for
each refund method listed within the returnRequest.getRefundMethodList() method. After creating
a refund method item, the method copies property values from the refund method to the refund item and
then adds the item to the repository. You must extend this method to add the custom refund method to the
repository. By default, this method handles the credit card and store credit refund methods.
5. Extend the ReturnManager.issueAlternateCreditType() method, which performs the crediting
against the refundMethod for all refund types that are not recognized by the issueCredits() method. You
extend the ReturnManager.
issueLaternateCreditType() method to credit the custom refund type. The issueCredits() method
handles credit card and store credit refund methods.
6. Extend the ReturnTools.getRefundMethod() method, which generates a ReturnMethod object from
the refundmethod repository item when the return request is reloaded. You extend this method to generate
a custom RefundMethod object whose properties are set from the repository item. By default, this method
handles credit card and store credit refund methods.
7. Add a display page fragment for the custom refund method. The refundType page displays the refund
methods from the returnRequest.getRefundMethodList() method. You must add a display page
fragment for the custom refund method. Update the payment group type configuration file by updating the
custom payment group displayRefundMethodPageFragment property value. This property identifies a
page fragment that specifies the location of a JSP fragment. The JSP fragment displays your custom refund
method type. The display fragment is used in the refund type and the return confirmation pages.
Configuring Ticket Disposition
ATG Commerce Service Center includes one ticket disposition monitor, /atg/commerce/custsvc/
ticketing/CSRTicketDispositionMonitor, which it adds to the ticketing manager’s
ticketDispositionMonitors property. This ticketing monitor’s shouldDiscard() and
shouldDiscardImmediately() methods both return false if a ticket contains any of the activity types listed
in the monitor’s nonDiscardableActivityTypes property.
This property is an array of activity type names. By default, nonDiscardableActivityTypes is set to a list
of all Commerce activity types, which means that CSRTicketDispositionMonitor will not allow a ticket to
7 Customizing ATG Commerce Service Center 99
be discarded if there are any Commerce activities associated with the ticket. You can change this behavior by
setting the value of this property to a different list of activity types. For additional information on ticketing, refer
to the ATG Service Installation and Configuration Guide.
CSC Environment Monitoring
An environment is the collective state of agent’s current working context. An environment monitoring interface
is defined for integrating applications with environment management. Use environment monitoring to
coordinate changes to the global environment objects.
ATG Commerce Service Center exposes the following global objects to the environment management system:
• Current Order - The order the agent is currently working on
• Current Catalog - The catalog context the agent is current working in
• Current Pricelist - The currently selected price list. This price list is used for pricing operations on the catalog,
cart and checkout pages
CSREnvironmentTools
Class atg.commerce.csr.environment.CSREnvironmentTools
Component /atg/commerce/custsvc/environment/CSREnvironmentTools
This component provides the core API for applying changes to the ATG Commerce Service Center environment
objects. It also provides the API for accessing the ATG Commerce Service Center managed environment objects.
CSREnvironmentMonitor
Class atg.commerce.csr.environment.CSREnvironmentMonitor
Component /atg/commerce/custsvc/environment/CSREnvironmentMonitor
This component detects changes, generates warnings and applies changes for ATG Commerce Service Center
managed objects.
CSREnvironmentConstants
Class atg.commerce.csr.environment.CSREnvironmentConstants
100 7 Customizing ATG Commerce Service Center
This static class exposes the environment change keys and their input parameters defined by ATG Commerce
Service Center. orderId is an example of an input parameter name required to execute the changeOrder
change.
EnvironmentChangeFormHandler, ChangeOrder
Class atg.svc.agent.environment.EnvironmentChangeFormHandler
atg.commerce.csr.environment.ChangeOrder
Component /atg/commerce/custsvc/environment/ChangeCatalogAndPriceList
/atg/commerce/custsvc/environment/ChangeOrder
/atg/commerce/custsvc/environment/CreateNewOrder
These components are used to perform ATG Commerce Service Center environment changes from UI gestures.
Configuring Audit Logging
ATG Commerce Service Center uses audit logging to record actions performed by CSC agents in the agent audit
repository.
Audit log records are saved in a standard GSA repository /atg/agent/logging/AuditRepository. The audit
log repository items provide an audit trail of actions perform by the agent.
Although audit log repository items can be added, update, or removed using the standard GSA repository API, a
series of components and classes are available to standardize the process of adding new items to the repository.
Note: There is no public API, other than direct GSA access, to update or remove audit log repository items.
Adding a New Agent Audit Log Record
The following steps occur when creating an audit log record:
1. Generate an AgentAudit event object (or extension thereof ) that contains all the relevant data to be
recorded. The AgentEvent identifies the type of audit record and has properties containing relevant
information for the log.
2. Fire the AgentAudit event object through the AgentMessageSource.
sendAgentEventMessage API. AgentMessageSource is defined as the message source for all AgentAudit
events in Dynamo Messaging.
3. AgentAuditLogger is defined as a message sink in Dynamo Messaging and receives the AgentAudit event
and queues it for distribution to the appropriate AuditLogRecorder.
4. AuditLogRecorder receives the AgentAudit event from the AgentAuditLogger and creates the
appropriate audit log repository item, sets the item’s properties from the AgentAudit event data, and adds it
to the repository.
7 Customizing ATG Commerce Service Center 101
When creating new audit records, you must modify each step of the audit log process.
Creating a New Agent Audit Log Record
The process outlined below uses creating a loyalty point redemption event as an example.
1. Add a new AgentAudit event subclass for the new audit record.
This may not be necessary if the AgentAudit class has all the necessary properties. In this case, you only
need to set the proper type of the event. Every event must extend AgentEvent. The following is an example
of a RedeemedLoyaltyPointsEvent:
package atg.commerce.csr.events;
import atg.agent.events.AgentEvent;
public class RedeemedLoyaltyPointsEvent extends AgentEvent {
public static final String CLASS_VERSION = "$Id: $$Change: $";
private static final long serialVersionUID = -5747213631038504108L;
int mPointsRedeemed;
public void setPointsRedeemed(int pPointsRedeemed) {
mPointsRedeemed = pPointsRedeemed;
}
public int getPointsRedeemed() {
return mPointsRedeemed;
}
2. Add the new audit log repository item definition for the new type.
Add an item descriptor to the audit repository for the new agent audit in the/atg/agent/logging/
auditrepository.properties file. Add an option to auditType property of the agent_audit item
descriptor. For example:
//Add the item descriptor
<item-descriptor name="RedeemedLoyaltyPoints" super-type="agent_audit"
sub-type-value="RedeemedLoyaltyPoints" cache-mode="disabled">
<table name="csr_loyalty" id-column-name="id">
<property name="pointsRedeemed" data-type="int" column-
name="points_redeemed" display-name-resource="pointsRedeemed"/>
<property name="orderId" data-type="string" column-name="order_id"
display-name-resource="orderId"/>
</table>
</item-descriptor>
//Add the auditType
<option value="RedeemedLoyaltyPoints" code="1020"/>
3. Create an AgentAuditLogger component using one of the base classes provided or an extension. This
component will receive the AgentAudit events of the new type. For example:
/atg/commerce/custsvc/logging/RedeemedLoyaltyPointsEventRecorder
$class=atg.agent.logging.ConfigurableAgentAuditRecorder
customProperties=\
pointsRedeemed=pointsRedeemed,\
orderId=orderId
ConfigurableAgentAuditRecorder provides a convenient way of defining a recorder where the
properties of the even map directly to the properties on the audit log repository item.
102 7 Customizing ATG Commerce Service Center
4. Configure the AgentAuditLogger with the new AgentAuditRecorder component mapped to the
appropriate audit type. Add an entry into the eventTypeToRecorderMap property of the /atg/agent/
logging/
AgentAuditLogger.properties component to provide information on the new event recorder. For
example,
eventTypeToListenerMap+=RedeemedLoyaltyPoints=/atg/commerce/custsvc/
logging/RedeemedLoyaltyPointsEventRecorder
5. Create an instance of the AgentAudit object and send it using the
AgentMessagesource.sendAgentEventMessage API.
private void sendRedeemedLoyaltyPointsEvent
(
String pAgentId,
String pCustomerId,
String pOrderId,
int pPointsRedeemed,
String pTicketId
)
{
RedeemedLoyaltyPointsEvent redeemedLoyaltyPointsEvent = null;
redeemedLoyaltyPointsEvent =
getAgentMessagingTools().createRedeemedLoyaltyPointsEvent();
redeemedLoyaltyPointsEvent.setActivityType
CSRAgentMessagingTools.REDEEMED_LOYALTY_POINTS_TYPE);
redeemedLoyaltyPointsEvent.setPointsRedemeed (pPointsRedeemed);
getAgentMessagingTools().getAgentMessageSource().sendAgentEventMessage
(redeemedLoyaltyPointsEvent, null,
"myApp.events.RedeemedLoyaltyPoint");
return;
}
Disabling Audit Logging
To reduce the amount of data stored, you may want the audit logging system to record only certain activities
and not others.
You can disable logging of an individual activity type by adding it to the disabledActivities property of the
/atg/agent/logging/AgentAuditLogger component. This property is an array of the names of the activity
types for which recording is disabled. For example, if you want to disable the recording of profile view events
and order view events, you could set this property to ProfileViewed,ViewOrder.
If you want to disable audit logging entirely, set the logEvents property of AgentAuditLogger to false.
Event Type Recorder
eventTypeToRecorderMap
ClaimItem /atg/commerce/custsvc/logging/
ClaimItemRecorder
7 Customizing ATG Commerce Service Center 103
Event Type Recorder
CancelOrder /atg/commerce/custsvc/logging/
OrderEventRecorder
CreateOrder /atg/commerce/custsvc/logging/
OrderEventRecorder
ApproveOrder /atg/commerce/custsvc/logging/
OrderEventRecorder
RejectOrder /atg/commerce/custsvc/logging/
OrderEventRecorder
ItemAddedToOrder /atg/commerce/custsvc/logging/
CommerceItemEventRecorder
ItemRemovedFromOrder /atg/commerce/custsvc/logging/
CommerceItemEventRecorder
ItemQuantityChanged /atg/commerce/custsvc/logging/
CommerceItemEventRecorder
ExchangeOrder /atg/commerce/custsvc/logging/
ReturnOrderRecorder
ReturnOrder /atg/commerce/custsvc/logging/
ReturnOrderRecorder
ReceiveReturnItem /atg/commerce/custsvc/logging/
ReceiveReturnItemRecorder
CreateOrderComment /atg/commerce/custsvc/logging/
CreateOrderCommentRecorder
AddPaymentGroup /atg/commerce/custsvc/logging/
PaymentGroupEventRecorder
AddShippingGroup /atg/commerce/custsvc/logging/
ShippingGroupEventRecorder
EditPaymentGroup /atg/commerce/custsvc/logging/
PaymentGroupEventRecorder
RemovePaymentGroup /atg/commerce/custsvc/logging/
PaymentGroupEventRecorder
EditShippingGroup /atg/commerce/custsvc/logging/
ShippingGroupEventRecorder
RemoveShippingGroup /atg/commerce/custsvc/logging/
ShippingGroupEventRecorder
GrantAppeasement /atg/commerce/custsvc/logging/
GrantAppeasementRecorder
104 7 Customizing ATG Commerce Service Center
Event Type Recorder
PriceOverride /atg/commerce/custsvc/logging/
PriceOverrideRecorder
SplitCostCenter /atg/commerce/custsvc/logging/
SplitCostCenterRecorder
SplitShippingGroup /atg/commerce/custsvc/logging/
SplitShippingGroupRecorder
SubmitOrder /atg/commerce/custsvc/logging/
OrderEventRecorder
ViewOrder /atg/commerce/custsvc/logging/
OrderEventRecorder
ViewOrderCostCenters /atg/commerce/custsvc/logging/
OrderEventRecorder
ViewOrderPayment /atg/commerce/custsvc/logging/
OrderEventRecorder
ViewOrderPromotions /atg/commerce/custsvc/logging/
OrderEventRecorder
ViewOrderReturns /atg/commerce/custsvc/logging/
OrderEventRecorder
ViewOrderShipping /atg/commerce/custsvc/logging/
OrderEventRecorder
ViewCreditCard /atg/commerce/custsvc/logging/
ViewCreditCardRecorder
AddOrderFixedAmountAdjustment /atg/commerce/custsvc/logging/
OrderManualAdjustmentRecorder
RemoveOrderFixedAmountAdjustment /atg/commerce/custsvc/logging/
OrderManualAdjustmentRecorder
SaveOrder /atg/commerce/custsvc/logging/
OrderEventRecorder
Viewing Audit Logs
ATG Commerce Service Center uses a system called audit logging to record actions performed by agents. Each
type of action has a corresponding repository item type. These repository item types are used to log agent
activity in the agent audit repository.
You can use the ACC to view these repository items:
1. Select the Content task area from the main ATG Control Center menu.
7 Customizing ATG Commerce Service Center 105
2. Select AuditAgentRepository from the submenu.
The system displays the following screen:
3. From the Items of Type drop-down list, select the type of item to view, and then click List.
If you select the first entry in the drop-down list, Agent Audit Record, the system displays all of the items
in the repository, regardless of type. If you select any other entry, the system displays only the items of the
specified type.
4. In the left pane, click the item to view.
The system displays the log information in the right pane. For example:
Configuring CSC Specific Ticket Activities
Because many of the actions taken by an agent in CSC are captured in the agent audit log, as well as ticket
activities, CSC provides a convenient way of creating a ticket activity from an AgentEvent.
The process mirrors that of recording an audit event whereby an AgentEvent is routed to a recorder
component, which saves the information in the repository. The recorders are mapped by the activity type. CSC
provides classes for the most common cases of creating activities from the events.
106 7 Customizing ATG Commerce Service Center
The following steps outline what is needed to record an AgentEvent as a ticket activity. This assumes that the
AgentEvent and audit log repository definitions are already in place. Refer to Configuring Audit Logging (page
100).
1. Define the new activity type in the TicketingRepository. You can define the ticket activity much the
same as the audit log definition for the same type. However, the ticket activity definition can be defined
as needed to meet your requirements. However, the only source for the ticket activity information is the
AgentEvent. For additional information, refer to the Defining New Ticket Activity Types section in the ATG
Service Installation and Configuration Guide.
2. Create the recorder components. The recorder component generates a ticket activity
from an AgentEvent. CSC provides two classes for the most common cases, the
atg.commerce.csr.ticketing.TicketingActivityRecorder class and the
TicketingPropertyUpdateRecorder class.
The TicketingActivityRecorder class is the base class for a recorder and supports the following features:
• Automatic creation of the ticket activity repository item based on the type contained in the AgentEvent
• The ability to configure a list of event properties that map to ticket activity properties. The recorder
automatically sets the values in the activity from those in the AgentEvent
• Automatic addition of the activity to the ticket ID referenced in the AgentEvent
• Automatic association of the order with the ticket. (Note that this only occurs when the AgentEvent
contains an orderId property)
• The ability to configure if the order related ticket activity should be added when the order is in a transient
state
• Automatic saving of the ticket after adding the activity
The TicketingPropertyUpdateRecorder class is an extension of TicketingActivityRecorder that
supports recording an AgentEvent that contains a List or PropertyUpdates. For example:
/myapp/recorders/LoyaltyPointRecorder
class=atg.commerce.csr.ticketing.TicketingActivityRecorder
applicationName=MyApplicationName
internalProfileRepository=/atg/userprofiling/InternalProfileRepository
orderRepository=/atg/commerce/order/OrderRepository
profileRepository=/atg/userprofiling/ProfileAdapterRepository
ticketingManager=/atg/ticketing/TicketingManager
customProperties=\
pointsRedeemed=pointsRedeemed,\
orderId=orderId
CSRAgentTools=/atg/commerce/custsvc/util/CSRAgentTools
ordersPropertyName=orders
saveTransientOrderActivities=false
3. Register the recorder component by activity type. Map the new recorder component by its activity type so an
AgentEvent of the same type will be routed to it for processing. For example:
/atg/commerce/custsvc/ticketing/TicketingEventListener.properties#13
$$Change: 447205 $
eventTypeToRecorderMap+=\
RedeemedLoyaltyPoints=/myapp/recorders/LoyaltyPointRecorder
7 Customizing ATG Commerce Service Center 107
Using Window Scoped Failover
With window scoped failover, upon server failure, an agent working on CSC remains logged in with the current
order, ticket, and profile information displayed in the global context area. The agent sees no change because of
the failover.
Properties of window scoped components can be targeted for window backup by adding them to the
windowBackupPropertyList property of the /atg/dynamo/servlet/pipeline/
WindowScopeManager component. Upon session failover, the configured property values will be restored.
These component property values must implement Serializable to be properly backed up.
The following components are failed over by CSC by default, in addition to the components that are failed over
by ATG Service:
• /atg/commerce/custsvc/order/ShoppingCart.current
• /atg/commerce/custsvc/order/ShoppingCart.restorableOrders
• /atg/commerce/custsvc/order/ShoppingCart.cloneEditState
• /atg/commerce/custsvc/order/ShoppingCart.loadTime
• /atg/commerce/custsvc/order/ShoppingCart.returnRequest
• /atg/commerce/custsvc/order/ViewOrderHolder.current
• /atg/commerce/custsvc/order/ViewOrderHolder.restorableOrders
• /atg/commerce/custsvc/order/ConfirmationInfo.order
• /atg/commerce/custsvc/order/ConfirmationInfo.profile
• /atg/commerce/custsvc/order/ConfirmationInfo.toEmailAddress
• /atg/commerce/custsvc/order/ConfirmationInfo.templateName
• /atg/commerce/custsvc/order/ConfirmationInfo.
autoConfirmationEmailAddress
• /atg/commerce/custsvc/order/ConfirmationInfo.extraData
• /atg/commerce/custsvc/returns/ReturnsDataHolder.returnRequestID
• /atg/commerce/custsvc/environment/CurrentPriceListHolder
• /atg/commerce/custsvc/environment/CurrentCatalogHolder
• /atg/commerce/custsvc/profile/AddressHolder.addresses
The following are also window scoped:
• /atg/commerce/order/purchase/PaymentGroupContainerService
• /atg/commerce/order/purchase/ShippingGroupContainerService
Adding Additional Components
Note: Making modifications to the existing window scoped and session scoped properties files may cause
failover to not work as expected.
108 7 Customizing ATG Commerce Service Center
Add failover components for any customized code that you have written by modifying the
WindowScopeManager.properties file in your custom module to add your customized components into the
windowBackupPropertyList+=/new/custom/component.properties list.
Extending ATG Commerce Service Center
This section discusses some of the classes in ATG Commerce Service Center that you may want to extend. You
can find additional information about these classes in the ATG API Reference for Commerce Service Center.
CSRShippingGroupFormHandler
Class atg.commerce.csr.order.CSRShippingGroupFormHandler
Component /atg/commerce/custsvc/order/ShippingGroupFormHandler
The CSRShippingGroupFormHandler class is a form handler that manages single and multiple
shipping stages of the checkout process. The CSRShippingGroupFormHandler extends core-commerce
atg.commerce.order.purchase.ShippingGroupFormHandler and additionally provides the capability to
add shipping related audit-logging events.
CSRPaymentGroupFormHandler
Class atg.commerce.csr.order.CSRPaymentGroupFormHandler
Component /atg/commerce/custsvc/order/PaymentGroupFormHandler
The CSRPaymentGroupFormHandler class is a form handler that manages billing stage of the checkout
process. The CSRPaymentGroupFormHandler extends core-commerce atg.commerce.order.
purchase.PaymentGroupFormHandler and additionally provides the capability to claim Store Credit, Gift
Certificate and optionally coupon. By default, the allowCouponClaim flag is set to false.
Modifying Keyboard Shortcuts
ATG Commerce Service Center allows you to modify the keyboardshortcuts that are used throughout the
application and Service Center.
7 Customizing ATG Commerce Service Center 109
To modify the shortcuts, you must modify the following files:
• Agent/script/keyboardShortcutsService.js
• Agent/script/keyboardTopicsService.js
• DCS-CSR/script/keyboardShortcutsCSC.js
• DCS-CSR/script/keyboardTopicsCSC.js
The keyboardShortcuts files are used to map keyboard shortcuts to published topics. The keyboardTopics
files are used to execute these topics and perform the specific functions.
The following is an example of a keyboard shortcut definition for the shortcut key ALT+6:
atg.keyboard.registerShortcut( "ALT+6", { shortcut: "ALT + 6", name: getResource("keyboard.service.customersTab.name"), description: getResource("keyboard.service.customersTab.description"), area: getResource("keyboard.area.workspace"), topic: "CustomersTab", notify: true });
Where:
• shortcut is the shortcut key that is shown in the help window
• name is the localized display name, shown in the help window
• description is the localized description, shown in the help window
• area is the localized functional area, shown in the help window
• topic is the name of the topic that is fired when this shortcut is pressed
• action is the optional JavaScript function that is called when the shortcut is pressed (used when a topic is
not available)
• notify is an attribute that determines whether the small popup window in the bottom right of the screen is
shown for the particular topic
Defining Global Keyboard Shortcuts
There are attributes that may be defined on a global basis for keyboard navigation. The Agent/src/
web-apps/Agent/script/keyboardNavigation.js file is the main keyboard navigation file. In it, you can
set the following variables:
var _showNotificationWindow = true;var _highlightAndFadePanels = true;var _highlightAndFadeNodes = true;
110 7 Customizing ATG Commerce Service Center
_showNotificationWindow determines whether the small notification window that pops up in the bottom
right part of the screen is shown when a shortcut is pressed. Each shortcut has an attribute called notify that
specifies the use of the notification window on a shortcut-by-shortcut basis. However, the use of the notification
window may be disabled if the _showNotificationWindow is set to false.
_highlightAndFadePanels provides a visual highlight as users jump from one panel to the next using the
panel shortcuts (CTRL+, CTRL+. ALT+, ALT+.). When this attribute is set to false, the panel highlighting will not
occur.
_highlightAndFadePanels provides a visual highlight as users tab throughout the Service Center. When this
attribute is set to false, the screen elements will not be highlighted.
Configuring Pages with Nucleus Components
Some portions of the UI use a technique that makes the rendering of pages, or portions of pages, configurable
through Nucleus components. This feature allows you to customize page content without unpacking the web
application, modifying its JSP, and then repackaging the modified application. Customization in this context
means the addition or replacement of JSP.
Examples of customizations with Nucleus components include the Products View Panel, which is accessed in /
panels/catalog/productView.jsp. The Product View Panel contains the ProductInformation panel, the
ProductSku panel and the CrossSellItems panels.
Additional pages that can be rendered include the ProductInformationPopup page, which includes the
QuickViewSkuTable, the ProductInformation panel and the ProductQuickViewPopup panels. The
ProductInformationPopup page is accessed from the item description.
7 Customizing ATG Commerce Service Center 111
Another example of customization includes the SkuProductPopup, which is accessed using the
SkuChangePopup. When the SkuChangePopup is activated, the SkuChangePanel and SkuChangeTable, as
well as the ProductInformation panel, are displayed.
You can change the SKU of CommerceItem objects in an order. The CSRCartModifierFormHandler contains
the handle method handleChangeSKUs() that uses the changeSKUsSuccessURL and changeSKUsErrorURL
properties, as well as the pre/post handler methods.
112 7 Customizing ATG Commerce Service Center
Customization Options
There are two general options for customizing page content.
• Simple Customization – This customization requires the configuration of an alternate URL in a component
property. Depending upon requirements, this customization may be all that is required for most
customization needs.
• Targeting Customization – Targeting customization is useful when one of a number of JSPs could be rendered
in a particular situation. In this situation, the decision of which JSP to render depends on complex rules, rules
that are expected to change often, or where it in instances where it is necessary to modify these rules without
restarting the application.
Targeting Customizations require writing targeting XML rules that contain information such as request
attributes, product and or order information, the current customer and the current agent, or other
information relevant to the functional area in question. Targeting rules normally target repository items,
however, targeting rules target Nucleus components that identify which JSPs to render.
Simple Customization
Simple customization involves writing custom JSPs and configuring Nucleus components to refer to that JSP. For
example, to replace the area of the Product View panel that displays product SKUS and allows agents to enter
quantities for each SKU, you would modify the /atg/commerce/custsvc/ui/
renderers/ProductSkuRenderer component.
Because renderer components are globally scoped, you can temporarily change the page though the Dynamo
HTML admin. All renderer components exist in the Nucleus configuration path at /atg/commerce/custsvc/
ui/renderers/. So if you are using JBoss, the SKU rendering component may be located at:
http://localhost:8080/dyn/admin/nucleus/atg/commerce/custsvc/ui/renderers/ProductSkuRenderer/
Changing the url property of this component to point to the new JSP temporarily implements the
customization. To make this configuration persistent, you must use a configuration file.
All components live under the Nucleus path /atg/commerce/custsvc/ui/renderers/. There are four
components for each renderer:
• BaseNameRenderer
• BaseNamePageData
• BaseNameSourceMap
• BaseNameTargeter
Pages that use renderers reference them using the path and the base name, for example:
<csr:renderer name="/atg/commerce/custsvc/renderers/ProductInformation">
There are optional RenderInfo properties, which include:
• pageOptions (Map) - A placeholder for settings used by the page
• ruleOptions (Map) - A container for use in targeting rules.
7 Customizing ATG Commerce Service Center 113
There is also a subclass RenderInfo for additional custom properties. A contextRoot property is available in
the atg.commerce.csr.rendering.RenderInfo class, allowing you to identify a web-app within CSC. The
web-app is executed when a user’s web browser references a URL that contains the web module’s context root.
For example, if you were to modify a renderer component such as /atg/commerce/custsvc/ui/
renderers/ProductInformationRenderer to identify the contextRoot property of:
contextRoot=/web-appurl=/web-app/test.html
This replaces the contents of the product information panel with whatever would be rendered by visiting
http://machine:port/web-app/test.html.
Targeting Customization
To customize the UI using the JSP targeting rules, one or more renderer component configuration must be
added to in the dynamo component path. Each renderer component represents one variation, or one JSP, of the
UI to display.
The following example describes the creation of a custom renderer for the SKU display and input area of the
Product View panel. The following /atg/commerce/custsvc/ui/renderers components are involved in this
example customization:
• ProductSkuRenderer: The default renderer for the product SKU area
• ProductSkuPageData: A component that will contain data from the enclosing page, such as product or
customer information
• ProductSkuSourceMap: The main component container used by the targeting rules. This component refers
to the PageData component above
• ProductSkuTargeter: The targeter configuration. This component refers to the SourceMap component
above, and one or more Renderer components
• To create a targeting customization:
• Create a new renderer component to represent the custom JSP. The basic properties of each renderer
component properties should be made in the /nucleus/
component/path/CustomRenderer.properties file:
# The base class for renderer components.
$class=atg.commerce.csr.rendering.RenderInfo
# An ID that uniquely identifies this renderer component in the
# domain in which it is used. All renderers currently shipped by
# ATG use the value "default" as their ID.
id=custom
# The custom JSP that performs the actual content rendering
url=/file/system/path/customSkuDisplay.jsp
• Create a RuleSetService configuration. This component identifies the rules file and contains settings for
when that file is loaded. In the /nucleus/component/path/
RuleSetService.properties file, add the following:
$class=atg.targeting.RuleSetService
114 7 Customizing ATG Commerce Service Center
# Path to rules file
rulesFilePath=/file/system/path/sku.rules
# Settings that control when/if rules files are loaded:
updatesEnabled=true
rulesFileCheckSeconds=0
The values used for updatesEnabled and rulesFileCheckSeconds above are useful when testing
targeting rules because they cause the rule file to be reloaded for every request. See the Targeting
documentation for more information about these values.
Note: If the RuleSetService has been configured to always reload targeting rules, it is easier to experiment
with rules by changing the file and causing the page to be redisplayed.
• Create the rules file for the RuleSetService configured Step 2. In the /file/system/path/sku.rules file,
add the following:
<ruleset>
<accepts>
<rule op="and">
<rule op="eq">
<!-- pageData is obtained from the SourceMap component -->
<valueof bean="pageData.product.id">
<valueof constant="prod10001">
</rule>
<rule op=eq>
<!-- target (display) the custom JSP -->
<valueof target="id">
<valueof constant="custom">
</rule>
</rule>
</accepts>
</ruleset>
In the example, the sku.rules file will target the custom renderer only when the product being
displayed has a value of “prod10001”. Only the first targeted component is displayed because the
TargetingFirstDroplet is used, so while multiple targets may match, only the first matching component’s
JSP will be rendered.
• Update the existing ProductSkuTargeter configuration to refer to the new Renderer component created in
Step 1, and to the RuleSetService configured in Step 2.
In localconfig, or another suitable Nucleus config directory, configure the properties of the /atg/
commerce/custsvc/ui/renderers/
ProductSkuTargeter/ProductSkuTarger.properties file with the following values:
# The collection of renderer components to be targeted. The
# following configures two renderers, the renderer created in step
# #1, and the default renderer provided with the product.
collectionComponents=ProductSkuRenderer,
/nuclues/component/path/CustomRenderer
# The targeting RuleSetService created in step #2
ruleSetService=/nucleus/component/path/RuleSetService
• Depending on the state of your Dynamo instance, you may need to restart the server for the settings to take
effect.
7 Customizing ATG Commerce Service Center 115
Creating a ProductSkuRenderer
To create a ProductSkuRenderer, modify the atg/commerce/custsvc/ui/renderers/
ProductSkuRenderer component path. The render components that should be extended are
atg.commerce.csr.rendering.RenderInfo with atg.commerce.csr.rendering.SkuRenderInfo.
Create new properties that describe how to render each table column. Property names can be actual SKU
property names or symbolic names such as price and status. Symbolic properties, or property names that do
not represent actual properties of the SKU, specify a JSP in the renderer property.
The ProductSkuRenderer uses the standard pageOptions property to specify form handler, URL properties
and other information. The pageOptions properties include:
# JSP fragment that renders the "Add to Cart" buttonactionRenderer=/renderers/order/sku/skuBrowserAction.jsp,# Form handler to useformHandler=/atg/…/order/CartModifierFormHandler,
The properties variable includes:
properties=viewItem,id,displayName,price,status,quantity
By default, the ProductSkuRenderer page uses skuItem.propertyNameto display the SKU property.
The property renderer specifies optional JSP files that are used to render named cells.
renderer= viewItem=/renderers/order/sku/viewItem.jsp, price=/renderers/order/sku/skuPrice.jsp, status=/renderers/order/sku/inventoryStatus.jsp, quantity=/renderers/order/sku/quantityInput.jsp
Each fragment renders its column header and column cell
<c:choose> <c:when test="${area == 'cell'}"> render cell content </c:when> <c:when test="${area == 'header'}"> render column header content </c:when></c:choose>
Customization Information
Custom Renderer components do not follow the naming convention of components involved in the renderer
configuration. Custom Renderer components may exist in any Nucleus component path. When working with
rule data:
• The custom renderer is targeted by ID in the example above, but any property of the
atg.commerce.csr.rendering.RenderInfo class, or subclass, can also be used in the targeting rules.
116 7 Customizing ATG Commerce Service Center
• The SourceMap component, ProductSkuSourceMap in the case of this example, contains data from the
current environment, including data calculated on the page in the pageData property of the SourceMap. This
data is available for use in targeting rules.
Flexible Customization uses a Targeter to target a collection of renderer components, so there are no repository
items involved. For example: atg.targeting.RuleBasedCollectionTargeter.
Targeting rules data is contained in the BaseNameSourceMap component, but can use data from the page, as
well as global, session, or request scoped data:
• Agent Profile
• Customer Profile
• Shopping Cart
Customizing the Order Summary Panel
The Order Summary panel, which is available to the agent when using the Commerce tab, displays order status
information. It also presents links based on the state of the order and where the agent is in the order process.
The Order Summary display is triggered when the agent performs a specific action or navigates to a specific
page.
Note: Page navigation changes take precedence over action changes.
The following actions trigger an update of the Order Summary display:
• Select an order, which also changes the active order in the Global Context Area
• Add a product to the shopping cart
• Cancel an exchange from within the exchange process
• Cancel a refund from within the refund process
The following processes trigger an update of the Order Summary display:
• Modification of an order on the Shopping Cart, Shipping Address, Shipping Method, Billing, Review Order and
Confirmation pages
• Scheduling a new or updating an existing schedule using the Schedule page
• A Return using Return Items, Return Type or the Return Confirmation pages
• Exchanges
To customize the Order Summary panel, override the Nucleus configuration files located in the config/atg/
commerce/custsvc/ordersummary directory. Then copy and modify the JSP files in DCS-CSR.war/panels/
ordersummary.
Adding a New Order Summary Step
1. If the new step fits into one of the pre-existing paths, such as modify order or returns, add a new properties
file to the configuration. If necessary, create a new JSP file. Pre-existing paths are indicated by the use of a
task-based name, such as exchange, modify, return, template, complete and submitted.
7 Customizing ATG Commerce Service Center 117
The properties files have the following entries:
• page= indicates the JSP file to display when the agent is in the step. If necessary, add a new JSP file and add
it to the page entry.
• content= indicates the web-app that contains your JSP files. If you do not indicate the web-app, then
the app server will try to find your new JSP in the DCS-CSR web application. Placing your JSP in the DCS-
CSR web app for testing is appropriate, but JSPs should be moved into your own web app for production.
Additionally, this will prevent your JSPs from being overwritten during any subsequent patch upgrades.
• visibleWhenInSteps= is a comma separated list of the steps where the JSP should be displayed. The
panel stack’s ID is used to identify the step. Use this for paths where steps appear immediately after the
step on which the agent is working. Leave the list blank if the step should always remain visible.
• completeWhenInSteps= is a comma separated list of the steps where the step should be in the complete
state. Completion is indicated when the step shifts from showing edit links to display the text “complete”.
These steps are performed after the step in which the agent is working. Leave the list empty if the step is
always complete.
2. Edit the properties files of the other steps in the path to provide information on the new step. For example,
add the ID of the new step to the visibleWhenInSteps= list of the steps before this new step in the path
when the agent is in the new step.
3. Ensure that one of the panels in the new panel stack calls the JavaScript function
atg.progress.update('someIdStringHere'), passing the ID of the panel stack. This lets the progress
bar know it needs to update itself, and indicates where the agent is in the process.
4. To add the JSP into your web applications, modify the Nucleus configuration properties files to identify which
web-app contains the JSP file. For example:
path=/panels/ordersummary/specialOffers.jsp
context=/my-web-app
Editing an Existing Order Summary Step
1. Copy an existing JSP file and rename the file.
2. Modify the JSP. For example, to modify the template billing step so that it is visually different than the
modifiable order billing step, copy the existing billing JSP file and make the changes as needed.
Adding a Custom Panel in ATG Service Center
Custom panels are created with Panels and Panel Stacks, which are repository based, and are used to control
tabs and tab content. The lowest level of detail is the Panel, which is contained within a Panel Stack.
118 7 Customizing ATG Commerce Service Center
To modify panels and panel stacks, use the /atg/svc/ServiceFrameworkRepository repository with the
repository import file /service/common/src/data/initial/svc_framework.xml and /DCS-CSR/src/
install/data/svc_framework.xml.
The repository contains the definitions for the tabs, the panel stacks and the panel definitions, as outlined in the
diagram below:
Repository Structure
The following is a sample Panel Stack Definition:
<add-item item-descriptor="PanelStackDefinition" id="WsCustomerPanelStack"> <set-property name="panelStackId" value="customerPanels"/>
7 Customizing ATG Commerce Service Center 119
<set-property name="errorPanelId" value="errorPanel"/> <set-property name="header" value="contentHeader"/> <set-property name="imageUrl" value="/iconcatalog/30x25/header_icons/ icon_panelcustMngmnt.gif"/> <set-property name="panelBackgroundTabStyle" value="contentBackgroundTab"/> <set-property name="panelSelectedTabStyle" value="contentSelectedTab"/> <set-property name="panelTitlebarTabbedStyle" value="contentTitlebarTabbed"/> <set-property name="panelTitlebarUntabbedStyle "value="contentTitlebarUntabbed"/> <set-property name="titleKey" value="panelStack.customerDetails.label"/> <set-property name="panelIds" value="errorPanel,ticketCustomerInformationPanel, ticketCustomerTicketHistoryPanel,ticketCustomerOrderHistoryPanel"/></add-item>
The following is a sample Panel Definition:
<add-item item-descriptor="PanelDefinition" id="WsTicketCustomerInformationPanel"> <set-property name="appId" value="workspace"/> <set-property name="panelId" value="ticketCustomerInformationPanel"/> <set-property name="templateIds" value="panelTemplate=panelTemplate"/> <set-property name="contentUrl" value="/panels/ticketCustomerInformationPanel.jsp"/> <set-property name="helpKey" value="panel.ticketCustomerInformationPanel.help"/> <set-property name="titleKey" value="panel.ticketCustomerInformationPanel.label"/> <set-property name="allowContentToggleYn" value="true"/> <set-property name="allowTabbingYn" value="true"/> <set-property name="accessRight" value="TicketsCustomerInformationPanel"/></add-item>
To avoid migration issues, replace the default PanelDefinition URL with a link to the custom JSP file and
include the default JSP from the custom page.
Customer Management Panel Configuration
You can customize the Customer Management Panel to display panels based upon your requirements by
adding or removing JSP files that display or manage customer specific data. Because the configuration is based
on components, you can perform module-specific customizations. The Commerce Service Center module
(DCS-CSR) extends the Customer Management Panel with Commerce-specific sections, such as Credit Cards,
Credits and Promotions. For additional information on Customer Management customizations, refer to the ATG
Commerce Programming Guide.
120 7 Customizing ATG Commerce Service Center
To modify the Customer Management Panel, modify the /atg/svc/agent/customer/
CustomerPanelConfig.properties to identify the panels to display as well as the context where the panel is
displayed. The following example creates the Profile, Notes and Addresses panels:
$class=atg.svc.agent.customer.CustomerPanelConfigsubSections= /panels/customer/profile.jsp, /panels/customer/notes.jsp, /panels/customer/addresses.jsp
contextRoots= /agent, /agent, /agent
Adding a New Panel to Commerce Service Center
New panels must be added to the Service Repository. To do this, perform an XML combine with the existing
svc_framework.xml file as outlined in the following example:
1. Update the Service Repository with definitions of the new CSC panels. ATG Service stores panels, panel stacks
and all other framework type objects in a repository, as defined in the install/data/svc_framework.xml
file.
Note: The panel definitions below point to the shopping cart. The following properties must be changed:
contentUrl, titleKey and resourceBundle.
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE gsa-template SYSTEM
7 Customizing ATG Commerce Service Center 121
"dynamosystemresource:/atg/dtds/gsa/gsa_1.0.dtd">
<add-item item-descriptor="PanelDefinition" id="myNewPanel1">
<set-property name="appId" value="workspace"/>
<set-property name="panelId" value="myNewPanel1"/>
<set-property name="accessRight" value="NewPanel1"/>
<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="DCS-CSR"/>
<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>
<add-item item-descriptor="PanelDefinition" id="myNewPanel2">
<set-property name="appId" value="workspace"/>
<set-property name="panelId" value="myNewPanel2"/>
<set-property name="accessRight" value="NewPanel2"/>
<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="DCS-CSR"/>
<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>
<add-item item-descriptor="PanelDefinition" id="myNewPanel3">
<set-property name="appId" value="workspace"/>
<set-property name="panelId" value="myNewPanel3"/>
<set-property name="accessRight" value="NewPanel3"/>
<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="DCS-CSR"/>
<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 panels can be added to any existing panel stack by updating the panelIds property. Similarly, the
panels may be added to a new panel stack.
Note: It is recommended that the JSPs for new panels should be housed in a custom web-app. If the JSPs are
housed in a custom web-app, the otherContext property of the PanelDefinition should be set to the
value of the context root of the containing web-app.
122 7 Customizing ATG Commerce Service Center
2. The list of valid framework components is managed by the FrameworkComponents service in the /atg/
svc/configuration/FrameworkComponents.properties file. Add the new panel to the end of the list in
the appropriate configuration layer with the flag set to true, for example:
componentIds+=\
myNewPanel=true
Note: The componentIds list is used for both panels and tabs.
Once the repository definition has been extended and the panels have been added to the required panel stack,
the Service database should be reloaded. The panels will then be visible.
Adding a Custom Tab
The following example displays the addition of a new myNewTab tab definition. It renders a new panel stack
called MyNewPS, which renders the three additional panels added above: myNewPanel1, myNewPanel2, and
myNewPanel3 (see Step 3 in Adding a New Panel to Commerce Service Center (page 120)).
In this example, the following properties will be changed for the tab definition:
Additional information regarding the following properties is available in the ATG Service Installation and
Configuration Guide
<?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="WsMyNewTabDefinition"> <set-property name="appId" value="workspace"/> <set-property name="tabId" value="myNewTab"/>
7 Customizing ATG Commerce Service Center 123
<set-property name="titleKey" value="myNewTab.resource"/> <set-property name="resourceBundle" value="atg.commerce.csr.FrameworkResources"/> <set-property name="accessRight" value="GlobalPanel"/><!-- Note: both cmcHelpfulPanels and helpfulPanels must be defined in case the user goes to Utilities | Preferences while on the Commerce tab. Preferences needs the next steps menu in the helpfulPanels panel stack. --> <set-property name="panelStackAssignments" value="MyNewPS=contentColumn,globalPanels=globalCell, helpfulPanels=sidebarColumn cmcHelpfulPanels=sidebarColumn preferencesPanel=contentColumn"/> <set-property name="currentPanelStacks" value="MyNewPS=contentColumn,cmcHelpfulPanels=sidebarColumn, globalPanels=globalCell"/> <set-property name="panelStackOrder" value="globalPanels,cmcHelpfulPanels,helpfulPanels,MyNewPS, preferencePanels"/> <set-property name="templateIds" value="contentHeader=contentHeaderTemplate"/> <set-property name="contentIds" value="actionJavaScript=myTabAction"/> </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="acme.csr.MyUserResource"/> <set-property name="panelIds" value="errorPanel,myNewPanel1,myNewPanel2, myNewPanel3"/> </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>
124 7 Customizing ATG Commerce Service Center
1. Once the new tab and panel stacks are defined, add the ContentDefinition item for the new tab action.
This defines the JavaScript action that will be attached to the TabDefinition item for the new tab (via the
contentIds map, see below) and will be executed when the tab is selected. For example:
<add-item item-descriptor="ContentDefinition" id="WsMyNewTabAction">
<set-property name="appId" value="workspace"/>
<set-property name="contentId" value="myNewTabAction"/>
<set-property name="mimeType" value="text/javascript"/>
<set-property name="body"><![CDATA[atgChangeTab(atg.service.framework.
changeTab('myNewTab'),null,null,null);]]></set-property>
</add-item>
2. The list of valid framework components is managed by the FrameworkComponents service in the /atg/svc/
configuration/FrameworkComponents.properties file. Add the new tab to the end of the list of your
customer application configuration layer with the flag set to true, for example:
componentIds+=\
myNewTab=true
Note: The same componentIds list is used for both panels and tabs.
Modifying a Tab Action
You can modify the action that a tab performs by modifying the ContentDefinition item for the action in the
Service Framework Repository. Once you have modified the item, you must define the JavaScript that will be run
when the tab is clicked.
Troubleshooting Tab Customization
When the application is started yet your new tab, panel stack or panel is not visible, check the following
common causes:
1. Verify that the enableYn property is set to true (the default value).
2. If you are using an access right other than GlobalPanels, verify that your access right has been created in
the appropriate repository. If unsure, set the accessRight to GlobalPanels, which is an access right with
no restrictions. The GlobalPanels access right can be used for both tabs and panels.
3. Verify that the tabId property (for a tab) or the panelId property (for a panel) is defined in the /atg/svc/
configuration/FrameworkComponents Nucleus component. If you are using a custom configuration layer,
use the ACC to confirm that the correct component is active. Note: This applies to tabs and panels only.
4. If a tab is not displaying, verify that the tabId for the tab was added to the tabIds property in the
workspace FrameworkDefinition item as described above.
7 Customizing ATG Commerce Service Center 125
5. If a panel stack is not displaying, verify that the panelStackId for the panel stack is added to the
panelStackAssignments, currentPanelStacks and panelStackOrder properties of the
TabDefinition item as described above.
6. If a panel is not displaying, verify that the panelId for the panel is added to the panelIds property in the
PanelStackDefinition item as described above.
7. If the top panel in the panel stack is not displaying, verify that the tabHolderYn property is set to true.
8. If a panel other than the top panel is not displaying, verify that the tabHolderYn property is false.
9. If tabbed panels are not displaying, verify the following:
• The first panel should be configured with tabHolderYn=true, currentPanelId=set to the same as
panelId and tabbedPanelIds=set to the list of panelId's of panels in the row of tabs not including first
panel
• The panels after the first panel should be configured with tabHolderYn=false and currentPanelId
and tabbedPanelIds set to null
• All the tabbed panels should be configured to alwaysTabbedYn=true, tabbedYn=true and
allowTabbingYn=true
10.If all the data is consistent and the item is still not displaying, check whether the following state-saving tables
have stale data that is interfering with the loading of the new data. In the admin schema, remove all the data
from the following tables and restart the server (if tables are non-empty):
• svc_cell_cfg
• svc_content_cfg
• svc_framewrk_cfg
• svc_fw_tab_cfg
• svc_panel_cfg
• svc_ps_pnl_cfg
• svc_pstack_cfg
• svc_skin_cfg
• svc_tab_cfg
• svc_tab_pnl_cfg
• svc_template_cfg
Customizing Forms
You can customize CSC forms using configuration layering. Extend the functionality of forms within Commerce
Service Center by modifying the fields within the form. CSC allows you to add or remove fields or to modify the
126 7 Customizing ATG Commerce Service Center
behavior of fields. For example, you can identify required fields within a specific form, by mapping to your own
JSP snippets that contain your customized layout. Once you have created your own customized JSP snippets,
you can modify the appropriate configuration property for that form to render your customizations.
Using default or extended fragments, you can modify the default forms, and/or append your customizations. If
these JSP snippets are not specified, the standard forms are rendered.
The following forms can be modified:
Page Form/Page Area
Customer Information Create New Customer
Customer information Edit/View Customer
Customer Search Customer Search or the Select Customer pop-up in the
shopping cart
Order Search Order Search
Product Catalog Product Search
Order View Display values
Scheduled Order Display values
Forms are customized by modifying the configuration properties files that define the JSP fragments that
replace and/or append the field. The JSP fragment is integrated within your page layout to display the new or
modified field. CSC uses a default JSP fragment that contains all of the standard fields displayed on a page, and
an optional extended JSP fragment used for creating additional fields.
The default page fragment component is mapped to the default JSP snippet in CSC but may be redirected with
a configuration property to your own JSP page. The page contains a dsp:include tag that reads the associated
configuration file and then includes the page defined by the page fragment component. For example, to change
the default fragment to your own code, you would change the page fragment’s servletContext and URL
properties to point to your page.
The extended page fragment component allows you to append content to the page without changing the
default page fragment. The extended page fragment component contains the same functionality as, and is
defined directly after, the default page fragment component.
The default and extended page fragment components are instances of atg.web.PageFragment, which are
used to define the location of the JSP file. The configuration files that define the page fragment components
contain the following properties to identify the JSP:
• servletContext - Specifies the context root of the JSP fragment that will be incorporated into the page
• URL - Specifies the URL of the JSP fragment to be incorporated into the page
Both the default and extended property files are instances of PageFragment, allowing a servletContext and
URL to be specified for the JSP snippet. As such, the servletContext and URL property descriptions can be
applied for both fragment types.
7 Customizing ATG Commerce Service Center 127
Location of Configuration Property File
The configuration property files for each modifiable form are located below. Note that there are two properties
files, one for the default configuration and one for the extended configuration. By default, the extended
properties files do not contain a reference to a JSP file. You can define a JSP for the extended fragment to
incorporate form properties that are specific to your business. The default URL and serverContext properties
have also been identified below:
Instance Location
View
Customer
<ATG9dir>/Service9.4/Service/Agent/config/atg/svc/
agent/ui/fragments/customer/CustomerViewDefault.properties
and
/CustomerViewExtended.properties
The default URL property is mapped to /include/customer/ProfileVewUIFragment.jsp
The default ServletContext property is mapped to agent
New
Customer
<ATG9dir>/Service9.4/Service/Agent/config/atg/svc/agent /ui/fragments/
customer/CustomerNewDefault.properties
and
/CustomerNewExtended.properties
The default URL property is mapped to/include/customer/ProfileNewUIFragment.jsp
The default ServletContext property is mapped to agent
Edit
Customer
<ATG9dir>/Service9.4/Service/Agent/config/atg/svc /agent/ui/fragments/
customer/CustomerEditDefault.properties
and
/CustomerEditExtended.properties
The default URL property is mapped to /include/customer/ProfileEditUIFragment.jsp
The default ServletContext property is mapped to agent
Customer
Search
and
Customer
Select
pop-up in
Shopping
Cart
<ATG9dir>/Service9.4/Service/Agent/config/atg/svc/ui/fragments/customer
/CustomerSearchDefault.properties
and
/CustomerSearchExtended.properties
The default URL property is mapped to /include/customer/
ProfileEditUIFragment.jsp
The default ServletContext property is mapped to agent
128 7 Customizing ATG Commerce Service Center
Instance Location
Product
Search
<ATG9dir>/CSC9.4/DCS-CSR/config/atg/commerce/custsvc/ui/fragments
/catalog/ProductSearchDefault.properties
and
ProductSearchExtended.properties
The default URL property is mapped to /include/catalog/
ProductSearchUIFragment.jsp
The default ServletContext property is mapped to DCS-CSR
Order
Search
<ATG9dir>/CSC9.4/DCS-CSR/config/atg/commerce/custsvc/ui/
fragments/order/OrderSearchDefault.properties
and
/OrderSearchExtended.properties
The default URL property is mapped to /include/order/OrderSearchUIFragment.jsp
The default ServletContext property is mapped to DCS-CSR
Order View <ATG9dir>/CSC9.4/DCS-CSR/config/atg/commerce/custsvc/ui/
fragments/order/OrderViewDefault.properties
and
/OrderViewExtended.properties
The default URL property is mapped to /include/order/OrderViewUIFragment.jsp
The default ServletContext property is mapped to DCS-CSR
Scheduled
Order View
<ATG9dir>/CSC9.4/DCS-CSR/config/atg/commerce/custsvc/ui/
fragments/order/ScheduledOrderViewDefault.properties
and
/ScheduledOrderViewExtended.properties
The default URL property is mapped to /include/order/
ScheuledOrderViewUIFragment.jsp
The default ServletContext property is mapped to DCS-CSR
Creating an Extended Page Fragment
Adding a new field to the end of the default fields is best done by modifying the appropriate extended
properties file. Any new fields will be displayed after the default fields. It is recommended that you use
configuration layering to create extended configuration files that reside within your own application module,
and point these files to the extended page fragments contained in your custom web application. This prevents
your customizations from being overwritten if CSC is updated, as the configuration properties are located in
your web application.
7 Customizing ATG Commerce Service Center 129
1. Create a JSP fragment file that provides the new field information.
2. Add the path of the newly created JSP file to the appropriate extended properties file. Specify the URL and
ServletContext for the appended file.
3. Save the extended properties file.
4. Create a new fragment and place it in the location specified by the URL property of the extended properties
file. Optionally, you can edit an existing JSP fragment that has been specified in the extended properties file
to include the new field information.
Note: The JSP fragments are dynamically included and the file will be compiled and executed before being
embedded into the form. As such, import any necessary components into your page to ensure successful
compiling.
Overriding the Default Page Fragment
You can make customizations to existing form fields such as adding a new field within or above the default field
layout. It is recommended that you use configuration layering to create configuration files that reside within
your own application module, and point these files to the extended page fragments within your own web
application. This prevents your customizations from being overwritten if CSC is updated, as the configuration
properties and JSPs are located in your web application.
1. Make a copy the appropriate default fragment.
2. Make your customizations to the copy of the default fragment. Specify the URL and ServletContext for the
web application file. Save your changes.
3. Update the appropriate version of the /localconfig configuration file to point to the new copy of the
default fragment.
Customizing Grids and Tables
ATG provides a method of customizing tables and grids with configuration layering. Using configuration
properties, you can identify the location and file names of JSP snippets to be included inside the default CSC
pages. If these JSP snippets are not specified, the default grid/table pages are displayed. However, you can
choose to specify these JSP snippets, and extend the grid components, by providing additional rendering
information and grid data that is integrated into the existing CSC grids.
Grids or tables can be modified to add columns, reorder or remove columns, change column widths or sorting,
as well as to change hover information.
Customizable Components
The customizable components of a grid or table are:
• Column title
• Column contents
• Column sorting
• Column width
130 7 Customizing ATG Commerce Service Center
• Number of rows displayed per page
• Number of rows displayed at a time per user scrolls
The following CSC grids can be modified:
Page Grid Location
Order History /atg/commerce/custsvc/ui/tables/order/
OrderHistoryGrid.properties
Scheduled Orders /atg/commerce/custsvc/ui/tables/order/
ScheduledOrdersGrid.properties
Customer
Information
Ticket History atg/svc/agent/ui/tables/ticket/
CustomerTicketGrid.properties
Exchange History /atg/commerce/custsvc/ui/tables/order/
ExchangeHistoryGrid.properties
Order View
Related Tickets /atg/commerce/custsvc/ui/tables/ticket/
RelatedTicketGrid.properties
Submitted Orders /atg/commerce/custsvc/ui/tables/order/
SubmittedOrdersGrid.properties
Scheduled Order
Related Tickets /atg/commerce/custsvc/ui/tables/ticket/
RelatedTicketGrid.properties
The following CSC tables can be customized:
Page Table Location
Customer Search Search Results /atg/svc/agent/ui/
CustomerProfileSearchUIConfiguration
Order Search Search Results /atg/commerce/custsvc/order/
OrderSearchUIConfiguration
Customizing Table Configuration
The TableConfiguration class is located in ATG Service Agent classes. The columns are defined in a list. The
properties for TableConfiguration are:
Property Description
columns List containing all columns in display order
7 Customizing ATG Commerce Service Center 131
Property Description
formHandlerPath The Nucleus path to the form hander that renders the results
imageClosed The file name of the image to render when the grid item detail is not visible
or is closed
imageOpen The file name of the image to render when the grid item detail is visible or is
open
imagePath The URL path to the images
tablePage The page fragment containing the grid implementation
tablePath The Nucleus path to the grid configuration component
rowsPerPage The number of items to fetch per server request, usually extracted from the
results form handler
defaultSortField The default sort column. This field should point to the configured
values in the particular column configuration to be sorted. The
ViewLink.sortField must match what is defined in the profile-
output-config.xml or the order-output-config.xml file.
defaultSortDirection The default sort direction, either ascending or descending. This field
should point to the configured values in the particular column configuration
to be sorted.
The following is an example of the /atg/commerce/custsvc/order/
OrderSearchUIConfiguration.properties file:
$class=atg.svc.agent.ui.tables.TableConfiguration$scope=global
columns=\ /atg/commerce/custsvc/ui/tables/order/search/Toggle,\ /atg/commerce/custsvc/ui/tables/order/search/ViewLink,\ /atg/commerce/custsvc/ui/tables/order/search/LastName,\ /atg/commerce/custsvc/ui/tables/order/search/FirstName,\ /atg/commerce/custsvc/ui/tables/order/search/Total,\ /atg/commerce/custsvc/ui/tables/order/search/ItemsReturned,\ /atg/commerce/custsvc/ui/tables/order/search/DateSubmitted,\ /atg/commerce/custsvc/ui/tables/order/search/Originator,\ /atg/commerce/custsvc/ui/tables/order/search/State,\ /atg/commerce/custsvc/ui/tables/order/search/WorkOn
imageClosed=icon_find.gifimageOpen=icon_find.gifimagePath=/images/icons/
rowsPerPage=10
defaultSortField^=/atg/svc/agent/ui/tables/customer/ViewLink.sortFielddefaultSortDirection^=/atg/svc/agent/ui/tables/customer/ViewLink.defaultSort
132 7 Customizing ATG Commerce Service Center
tablePath=/atg/commerce/custsvc/ui/tables/order/search/OrderSearchResultsTabletablePage=/atg/commerce/custsvc/ui/tables/order/search/OrderSearchTablePage
Customizing Grid Configuration
The GridConfiguration object is located in ATG Service Agent classes and extends the
TableConfiguration class. The columns are defined in order in an array of ColumnConfiguration
components. The properties for GridConfiguration are:
Property Description
columns The array of ColumnConfiguration components that specify the columns
for the grid in display order
dataModelPage The page fragment component that contains the data model (for example,
JSON). Include the full Nucleus path to the component
detailFormId The DOM ID of the form node to submit to retrieve an item detail
formHandlerPath The Nucleus path to the form handler that renders the results
gridHeight The value assigned to the height CSS style for the table to determine its visible
height.
gridInstanceId The JavaScript variable name that should be unique for each instance of the
table in the application
gridPage The page fragment containing the grid implementation
gridPath The Nucleus path to the grid configuration component
gridWidgetId The Dojo ID of the table widget that should be unique for each instance of the
table in the application
imageClosed The file name of image to render when the grid item detail is not visible or
closed
imageOpen The file name of image to render when the grid item detail is visible or open
imagePath The URL path to the images
itemDetailPage The page fragment component containing the item details (currently
implemented as a hover popup)
pageBaseOffset The base of the paging: 0 for 0-based paging, 1 for 1-based paging, etc.
pageIndexElementName The element name of the page index form input
progressNodeId The optional ID for a DOM node to render status messages, such as ‘search in
progress...’ or ‘No results found.’ etc.
rowsPerPage The size of the result to send back from the form handler in each page
7 Customizing ATG Commerce Service Center 133
Property Description
searchFormId The DOM ID of the form node to submit to retrieve orders
selectLink An anchor tag template with pattern replacement for selecting the item in the
application
viewLink An anchor tag template with pattern replacement for viewing the item in the
application
The following is an example of the /atg/commerce/custsvc/ui/tables/order/
OrderHistoryGrid.properties file:
$class=atg.svc.agent.ui.tables.GridConfiguration# invisible data columns: DBState
columns=\ /atg/commerce/custsvc/ui/tables/order/Toggle,\ /atg/commerce/custsvc/ui/tables/order/ViewLink,\ /atg/commerce/custsvc/ui/tables/order/Total,\ /atg/commerce/custsvc/ui/tables/order/ItemCount,\ /atg/commerce/custsvc/ui/tables/order/ItemSummary,\ /atg/commerce/custsvc/ui/tables/order/SubmittedDate,\ /atg/commerce/custsvc/ui/tables/order/Origin,\ /atg/commerce/custsvc/ui/tables/order/State,\ /atg/commerce/custsvc/ui/tables/order/SelectLink,\ /atg/commerce/custsvc/ui/tables/order/ID,\ /atg/commerce/custsvc/ui/tables/order/DBState
rowsPerPage=10
formHandlerPath=/atg/commerce/custsvc/order/OrderHistoryTableFormHandler
gridHeight=450pxgridInstanceId=atg.commerce.csr.order.historyGridInstancegridPath=/atg/commerce/custsvc/ui/tables/order/OrderHistoryGridgridWidgetId=atg_commerce_csr_customer_order_searchResultsTableprogressNodeId=atg_commerce_csr_order_resultsGridStatussearchFormId=orderHistoryListForm
dataModelPage=/atg/commerce/custsvc/ui/tables/order/OrderDataPagegridPage=/atg/commerce/custsvc/ui/tables/order/OrderGridPageitemDetailPage=/atg/commerce/custsvc/ui/tables/order/OrderDetailPage
Customizing Column Configuration
The ColumnConfiguration object is located in Service Agent.
Column Configuration with Dojo
The properties for ColumnConfiguration within Dojo are:
134 7 Customizing ATG Commerce Service Center
Property Description
cellRendererPage The page fragment component that can contain a client-side JavaScript function to
render the cell contents. Includes the full Nucleus path to the component
dataRendererPage The page fragment component that returns server-side data in JSON that inserts a
cell. Includes the full Nucleus path to the component
defaultSort Is set to either ascending or descending sorting or left blank for no sorting.
field The field name identifier for the data to render in the column from the data model.
UI-only columns without a backing data representation should leave the field
parameter undefined.
sortField The name of the data model field on which to sort, which is different than field.
If this property is undefined and sorting is enabled using defaultSort, the data
is sorted on the field property. If this property is defined and sorting is enabled
using defaultSort, the data is sorted on the sortField property. This property
allows a column to contain rendering and markup that does not interfere with the
sorting of the field. For example, the ViewLink column can have a link to view
an item where the column is not sorted on the link markup, but on a separate
corresponding data value.
isVisible Whether to display the column in the UI or only to send back the data for the
column. This is useful for JavaScript widgets that store invisible column data
for other columns. For example, an onClick function in the ID field can use an
invisible DBState field to identify what to do when an order is opened.
resourceBundle The resource bundle that contains the column display name
resourceKey The key that references the column display name in the resource bundle
width The extent of the column using the Dojo grid syntax (e.g. ‘5em’ or ‘auto’)
styles The column CSS styles. Note: Styles are not modifiable for tables.
The following is an example of the /atg/commerce/custsvc/ui/tables/order/
ViewLink.properties column configuration:
$class=atg.svc.agent.ui.tables.ColumnConfiguration
defaultSort=ascendingfield=viewLinksortField=idwidth=4emresourceBundle=atg.commerce.csr.MessagesresourceKey=view-orderisVisible=true
cellRendererPage=/atg/commerce/custsvc/ui/tables/order/ViewLinkPagedataRendererPage=/atg/commerce/custsvc/ui/tables/order/ColumnRendererPage
7 Customizing ATG Commerce Service Center 135
Column Configuration using an HTML Table
The properties for ColumnConfiguration using an HTML table are:
Property Description
dataRendererPage The page fragment component that returns server-side data in JSON that inserts a
cell. Includes the full Nucleus path to the component
field The field name identifier for the data to render in the column from the data model.
UI-only columns without a backing data representation should leave the field
parameter undefined.
isVisible Whether to display the column in the UI or only to send back the data for the
column. This is useful for JavaScript widgets that store invisible column data
for other columns. For example, an onClick function in the ID field can use an
invisible DBState field to identify what to do when an order is opened.
resourceBundle The resource bundle that contains the column display name
resourceKey The key that references the column display name in the resource bundle
width The extent of the column using the Dojo grid syntax (e.g. ‘5em’ or ‘auto’)
The following is an example of the /atg/svc/agent/ui/tables/customer/LastName.properties column
configuration:
$class=atg.svc.agent.ui.tables.ColumnConfiguration
field=lastNameresourceBundle=atg.svc.agent.WebAppResourcesresourceKey=customer.results.lastNameisVisible=true
dataRendererPage=/atg/svc/agent/ui/tables/customer/ColumnRendererPage
Customizing Column Attributes
The steps for customizing column title, sorting and width are similar in that they update properties in the
column configuration component. Note: Do not use quotes when setting values in this map.
To begin customization, override the column configuration by performing the following:
1. Create a new application module for customizations. Include this module when starting JBoss. Refer to the
ATG Installation and Configuration Guide for information on creating new application modules and starting
JBoss.
2. Locate the properties file that defines the appropriate column configuration.
3. Inside the customization module, create a properties file at the corresponding path that contains no
properties.
136 7 Customizing ATG Commerce Service Center
Customizing a Column Title
1. Create or edit a resource bundle for customized strings in the customization module.
2. In the properties file for the column, update the resourceBundle and resourceKey properties to point to
the corresponding resource bundle and key that contain the customized string. This overrides the default
values for these properties. For example:
defaultSort=ascending
field=viewLink
sortField=id
width=4em
resourceBundle=atg.commerce.csr.newMessages
resourceKey=new-view-order
isVisible=true
Configuring Column Sorting
1. In the appropriate properties file for the column, set the defaultSort property to either ascending or
descending. Removing the property or setting the property to an empty string will remove sorting. For
example:
defaultSort=ascending
field=viewLink
sortField=id
width=4em
resourceBundle=atg.commerce.csr.Messages
resourceKey=view-order
isVisible=true
2. To configure a Dojo-grid column to sort on a field other than the data field that is rendered in the column, set
the sortField to any field in the data model.
For example, your column might display a data field containing an HTML link or JavaScript, such as viewLink,
which is not appropriate for sorting. By setting the sortField property to ID, the column can still be sorted
by the corresponding ID property.
3. Configure an HTML-grid column by configuring the /atg/svc/agent/ui/
CustomerProfileSearchUIConfiguration.properties or /atg/commerce/custsvc/order/
OrderSearchUIConfiguration.properties files.
Customizing a Column Width
1. In the properties file for the column, update the width property to the desired CSS width specification, for
example. 4em.
2. To set the column width to fill the remaining space on the screen, set the width to auto.
Customizing Page Configuration
The table and column configuration components use the PageFragment component in Web UI to reference JSP
pages located in the /atg/web/PageFragment directory.
• URL – the URL of the page to include
7 Customizing ATG Commerce Service Center 137
• servletContext – the context root of the application that contains the page
The following is an example of the /atg/commerce/custsvc/ui/tables/order
/ColumnRendererPage:
$class=atg.web.PageFragment
URL=/include/order/columnRenderer.jspservletContext=DCS-CSR
Customizing Column Content
The data renderer page displays the content to render within the column.
Column Content using Dojo Grids
By default, the data renderer page is called for each column when the grid items are iterated. The following
parameters are passed to the data renderer page:
Parameter Description
field The string identifier of the column to render as defined in the ColumnConfiguration
object.
colIndex The zero-based index of the column.
[bean] The object(s) containing the data for the grid item. They will vary depending on the
data being rendered. For an order, the item is a single orderItemMap bean.
The following is an example from the /web-apps/DCS-CSR/include/order/columnRenderer.jsp file:
<dsp:getvalueof var="field" param="field"/><dsp:getvalueof var="colIndex" param="colIndex"/><dsp:getvalueof var="orderItemMap" param="orderItemMap"/>
<c:choose><c:when test="${field == 'id'}"> "id":"${orderItemMap.id}",</c:when>
<c:when test="${field == 'viewLink'}"> <fmt:bundle basename="atg.commerce.csr.Messages"> "viewLink":"<a href=\"#\" class=\"blueU\" title=\" <fmt:message key="view-order"/>\" onclick=\"atg.commerce.csr.order.viewExistingOrder(\'${orderItemMap.id}\',\ '${orderItemMap.state}\');return false;\">${orderItemMap.id}</a>" </fmt:bundle></c:when>
138 7 Customizing ATG Commerce Service Center
...
Column Content using HTML Tables
The data renderer page displays the content to render within the column. By default, the data renderer page is
called for each column heading and data cell. The following parameters are passed to the data renderer page:
Parameter Description
field The string identifier of the column to render as defined in the
ColumnConfiguration object
customerItemMap The current customer item being rendered
resourceBundle The resource bundle that defines the resource keys
resourceKey The key that maps to the resource string
isPopup Identifies if the search table is a pop up. For example, the customer search from the
Shopping Cart page is a pop up table
isHeading Identifies if a heading should be rendered
Configuring Column Content
The data renderer page displays the content to render within the column. By default, this page is called for each
column when the grid items are iterated. The following parameters are passed to the data renderer page each
time it is included:
• field - The string identifier of the column to render as defined in the ColumnConfiguration object
• colIndex - The zero-based index of the column
• [bean] - The object(s) containing the data for the grid item. This varies depending on the data being rendered.
For example, for an order, the item is a single orderItemMap bean.
Before customizing the data renderer page, perform the following steps:
1. Create a new application module for customizations. Include this module when starting JBoss. Refer to the
ATG Programming Guide for information on creating new application modules and the ATG Installation and
Configuration Guide for information on starting JBoss.
2. Locate the properties file that defines the column configuration.
3. Inside the customization module, create an empty properties file at the corresponding path.
Customizing the Data Render Page
1. Create a new JSP file in the module that will render the customized data.
2. In this module, create a new PageFragment properties file under /atg/commerce/custsvc/ui/tables.
For example, create a NewColumnRendererPage.properties file.
7 Customizing ATG Commerce Service Center 139
3. In the properties file for the page fragment, set the URL and servletContext to reference the JSP page
created in the customization module. For example:
# @version $Id: //application/DCS-CSR/atg/commerce/custsvc/ui/tables/
order/NewColumnRendererPage.properties#1 $$Change: 523100 $
$class=atg.web.PageFragment
URL=/include/order/newColumnRenderer.jsp
servletContext=DCS-CSR
4. In the properties file for the column or grid, update the dataRendererPage property to point to the
PageFragment properties file. For example:
dataRendererPage=NewColumnRendererPage
Example: Customizing Column Content
This example replaces the Origin column in the default application with a Last Modified column in the Order
History grid.
1. In the resource bundle at /acme/resources/Resources.property, add a new key for the column title.
lastModifiedDate=Last Modified
To avoid a recompile of the JAR, add the new resource bundle and key into your <ATG9dir>/locallib
directory. A server restart is required once you have created the key.
2. In the sample application, create a grid properties file at /atg/commerce/custsvc/
ui/tables/order/OrderHistoryGrid.properties to override the default file. Override the columns
property with the new columns; however, ensure that the invisible columns are included so that the order
links work correctly:
invisible data columns: DBState
columns=\
/atg/commerce/custsvc/ui/tables/order/Toggle,\
/atg/commerce/custsvc/ui/tables/order/ViewLink,\
/atg/commerce/custsvc/ui/tables/order/Total,\
/atg/commerce/custsvc/ui/tables/order/ItemCount,\
/atg/commerce/custsvc/ui/tables/order/ItemSummary,\
/atg/commerce/custsvc/ui/tables/order/SubmittedDate,\
/atg/commerce/custsvc/ui/tables/order/LastModified,\
/atg/commerce/custsvc/ui/tables/order/State,\
/atg/commerce/custsvc/ui/tables/order/SelectLink,\
/atg/commerce/custsvc/ui/tables/order/DBState
3. In the sample application, create the properties file for the column at /atg/commerce/custsvc/ui/
tables/order/LastModified.properties that contains the configuration for the new column:
$$Change: 523100 $
$class=atg.svc.agent.ui.tables.ColumnConfiguration
field=lastModified
width=5em
resourceBundle=acme.resources.Resources
resourceKey=lastModifiedDate
defaultSort=descending
isVisible=true
dataRendererPage=/atg/commerce/custsvc/ui/tables/order/
140 7 Customizing ATG Commerce Service Center
LastModifiedRendererPage
4. In the sample application, create the properties file for the content page at /atg/commerce/custsvc/ui/
tables/order/
LastModifiedRendererPage.properties:
$class=atg.web.PageFragment
URL=/panels/order/lastModifiedRenderer.jsp
servletContext=/Sample-DCS-CSR-App
5. In the sample application, create a JSP page at the location referred to by the page configuration. The JSP
renders the last modified date property from the order:
<%@ include file="/include/top.jspf"%>
<dsp:page>
<fmt:bundle basename="acme.resources.Resources">
<dsp:getvalueof var="field" param="field"/>
<dsp:getvalueof var="colIndex" param="colIndex"/>
<dsp:getvalueof var="orderItemMap" param="orderItemMap"/>
<c:choose>
<c:when test="${field == 'lastModified'}">
"lastModified":"${orderItemMap.lastModifiedDate}"
</c:when>
<c:otherwise>
</c:otherwise>
</c:choose>
</fmt:bundle>
</dsp:page>
6. Test and verify that the last modified date column is rendered in the grid.
Note: Default date formats can be modified using the webAppResources.properties file in the /WEB-INF
directory.
Example: Creating Calculated Content
The following provides an example that returns calculated content.
1. Follow the steps for creating customized content, as outlined in the Customizing Column Content (page
137) section.
2. Create a JSP page that returns a calculation of one or more data items. For example:
<%@ include file="/include/top.jspf"%>
<dsp:page>
<fmt:bundle basename="acme.resources.Resources">
<dsp:getvalueof var="field" param="field"/>
<dsp:getvalueof var="colIndex" param="colIndex"/>
<dsp:getvalueof var="orderItemMap" param="orderItemMap"/>
<c:choose>
<c:when test="${field == 'totalNoTax'}">
<dsp:tomap var="priceInfo" value="${orderItemMap.priceInfo}"/>
<c:set var="totalValue"><dsp:valueof converter="currency"
value="${priceInfo.amount+priceInfo.shipping}"/></c:set>
"totalNoTax":"${totalValue}",
</c:when>
...
7 Customizing ATG Commerce Service Center 141
3. Test and verify that the calculation is rendered in the grid.
Working with Columns
The following steps provide information on how to add, delete or reorder columns.
Adding a Column
1. Follow the steps above to customize column content to create the new column. However, instead of opening
an existing column configuration file, create a new properties file for the column.
2. Set the column properties as outlined above.
3. Open the properties file for the grid under /atg/commerce/custsvc/ui/tables and insert the column
using the full Nucleus path to the column configuration component in the desired location of the columns
list.
Removing a Column
1. Open the properties file for the grid under /atg/commerce/custsvc/ui/tables.
2. Delete the column identifier from the columns list.
Reordering Columns
1. Open the properties file for the grid under /atg/commerce/custsvc/ui/tables.
2. Reorder the column identifiers within the columns list.
Example: Adding a New Column to the Order Search Results
1. Create a new column as outlined above in the Adding a Column (page 141) section.
2. Add your new column to the order-output-config.xml file. Adding the store-as-meta-index
parameter allows your search engine to store the data within this column in a sort-enabled format. For
example, to add a Last Modified column, you would create the following:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE item PUBLIC "-//Art Technology Group, Inc.//DTD Repository
Ouput Specifier 1.0//EN" "http://www.atg.com/dtds/search/indexing-
dependency-schema.dtd">
<item item-descriptor-name="order">
<meta-properties>
<property name="lastModifiedDate" type="date" store-as-meta-
index="false" />
</meta-properties>
</item>
3. Run the /dyn/admin/nucleus/atg/commerce/search/
OrderOutputConfig/bulkload method.
4. Create a property file for the new column in the /atg/commerce/custsvc/ui/
tables/order/search directory. Using the LastModifiedDate example, you would create a /atg/
commerce/custsvc/ui/tables/order/search/
LastModified.properties file. For example:
$class=atg.svc.agent.ui.tables.ColumnConfiguration
142 7 Customizing ATG Commerce Service Center
field=lastModified
sortField=lastModifiedDate
width=5em
resourceBundle=acme.resources.Resources
resourceKey=lastModifiedDate
defaultSort=descending
isVisible=true
dataRendererPage=/atg/commerce/custsvc/ui/tables/order/search/
LastModifiedRendererPage
5. Create a new dataRendererPage property file in the location indicated in the new column property file you
just created. This file will identify the URL page to use, as well as the context application.
Using the previous example, you would create a /atg/commerce/custsvc/ui/
tables/order/search/LastModifiedRendererPage.properties file that contained the following:
$class=atg.web.PageFragment
URL=/panels/order/search/lastModifiedRenderer.jsp
servletContext=/Sample-DCS-CSR-App
6. Create the new JSP file at the location identified above in the URL parameter.
When you create the JSP file use the isHeading parameter to determine whether to render a heading
or a data row. If rendering a heading you can display the heading title or information can be passed into
the orderSearchResultSortHeading.jsp file, which allows users to sort on this column. Note: The
sortField used must be the same as what is used in the XML file because this parameter is passed to the
search engine. For example:
<%--
Last modified date renderer example for order search table
@version $Id: //application/DCS-CSR/main/sample-app/src/web-apps/Sample-
DCS-CSR-App/panels/order/search/lastModifiedRenderer.jsp $
@updated $DateTime: 2009/04/01 11:29:04 $
--%>
<%@ include file="/include/top.jspf"%>
<dsp:page>
<fmt:bundle basename="acme.resources.Resources">
<dsp:getvalueof var="field" param="field"/>
<dsp:getvalueof var="sortField" param="sortField" />
<dsp:getvalueof var="orderItemMap" param="orderItemMap"/>
<dsp:getvalueof var="isHeading" param="isHeading" />
<dsp:getvalueof var="resourceBundle" param="resourceBundle" />
<dsp:getvalueof var="resourceKey" param="resourceKey" />
<c:if test="${empty isHeading}">
<c:set var="isHeading" value="false" />
</c:if>
<c:choose>
<c:when test="${field == 'lastModified' and isHeading=='false'}">
<c:out value="${orderItemMap.lastModifiedDate}" />
</c:when>
<c:when test="${field == 'lastModified' and isHeading=='true'}">
<dsp:include src="/panels/order/orderSearchResultSortHeading.jsp"
otherContext="${CSRConfigurator.contextRoot}">
<dsp:param name="resourceBundle" value="${resourceBundle}"/>
<dsp:param name="resourceKey" value="${resourceKey}"/>
7 Customizing ATG Commerce Service Center 143
<dsp:param name="fieldName" value="${sortField}"/>
</dsp:include>
</c:when>
<c:otherwise>
</c:otherwise>
</c:choose>
</fmt:bundle>
</dsp:page>
7. Create the new table column configuration and add the new column information by creating a /atg/
commerce/custsvc/order/OrderSearchUIConfiguration.
properties file. The following example extends the default values by identifying the number of results per
page, as well as enabling search on the new column:
$class=atg.svc.agent.ui.tables.TableConfiguration
$scope=global
columns=\
/atg/commerce/custsvc/ui/tables/order/search/Toggle,\
/atg/commerce/custsvc/ui/tables/order/search/ViewLink,\
/atg/commerce/custsvc/ui/tables/order/search/LastName,\
/atg/commerce/custsvc/ui/tables/order/search/FirstName,\
/atg/commerce/custsvc/ui/tables/order/search/Total,\
/atg/commerce/custsvc/ui/tables/order/search/ItemsReturned,\
/atg/commerce/custsvc/ui/tables/order/search/DateSubmitted,\
/atg/commerce/custsvc/ui/tables/order/search/LastModified,\
/atg/commerce/custsvc/ui/tables/order/search/Originator,\
/atg/commerce/custsvc/ui/tables/order/search/State,\
/atg/commerce/custsvc/ui/tables/order/search/WorkOn
rowsPerPage=3
defaultSortField^=/atg/commerce/custsvc/ui/tables/order/search/
LastModified.sortField
defaultSortDirection^=/atg/commerce/custsvc/ui/tables/order/search/
LastModified.defaultSort
Changing the Item Detail (Hover) Page
The following provides information on changing the page that is displayed for the order detail, which is
configured as a hover object.
1. Create a JSP page to render the order item detail in a new application module. If necessary, use the existing
item detail page located at /panels/order/
orderDetail.jsp as a template for the new file.
2. Open the properties file for the grid and find the itemDetailPage property. This component contains the
URL to the item detail page.
3. Create a new properties file for the item detail page component under /atg/commerce/custsvc/ui/
tables. Override the servletContext and URL properties to point to the new file.
144 7 Customizing ATG Commerce Service Center
Appendix A. ATG Commerce Service Center Database Tables 145
Appendix A. ATG Commerce Service
Center Database Tables
This appendix describes the database tables used by ATG Commerce Service Center.
ATG Commerce Service Center Core Tables
ATG Commerce Service Center uses the following database tables to store customer service information. These
tables are installed by the <ATG9dir>/CSC9.4/DCS-CSR/sql/db_components/database-vendor/DCS-
CSR_ddl.sql script.
The csr_order_cmts table is used by the Commerce order repository. The Nucleus component for this
repository is /atg/commerce/order/OrderRepository. The rest of the tables described in this section are
used by the ATG Commerce Service Center returns and exchanges repository (/atg/commerce/custsvc/
CsrRepository).
csr_order_cmts
This table stores agent comments associated with orders.
Column Data Type Constraint
comment_id varchar(40) not null
(primary key) The unique ID associated with the comment.
order_id varchar(40) not null
(primary key) The ID of the order the comment is associated with. References dcspp_order
(order_id).
agent_id varchar(40) null
The profile ID of the agent who submitted the comment.
comment_data varchar(254) not null
The text of the comment.
146 Appendix A. ATG Commerce Service Center Database Tables
Column Data Type Constraint
creation_date timestamp null
The date and time when the comment was submitted.
version integer not null
The GSA version of the repository item.
csr_exch
This table stores information about order exchanges and returns.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the return.
order_id varchar(40) not null
The ID of the order the return is associated with. References dcspp_order
(order_id).
created_date timestamp not null
The date and time the return was submitted.
status varchar(40) not null
The current status of the return. Possible values: pending_customer_action,
partial_return, full_return, complete.
rma varchar(40) null
The RMA number associated with the return. (This value is the same as the
ID of the return.)
repl_order_id varchar(40) null
The ID of the order containing the replacement items for the return.
bal_pmt_id varchar(40) null
The ID of the balance payment for the return.
sugg_tax_refund double precision not null
The suggested tax refund calculated by return processing.
actl_tax_refund double precision not null
Appendix A. ATG Commerce Service Center Database Tables 147
Column Data Type Constraint
The actual tax refund given by the agent.
sugg_ship_refund double precision not null
The suggested shipping refund calculated by return processing.
actl_ship_refund double precision not null
The actual shipping refund given by the agent.
other_refund double precision not null
Other refund types.
sc_recipient varchar(40) null
The profile ID of the customer receiving any store credits associated with
this return.
proc_immed tinyint not null
check (proc_immed in (0,1))
Boolean indicating whether the return should be processed immediately
(i.e., before the return shipment is received).
processed tinyint not null
check (processed in (0,1))
Boolean indicating whether the return has been processed.
origin_of_return integer null
The numeric code for the origin of the return.
agent_id varchar(40) null
The unique ID of the agent.
csr_exch_cmts
This table stores agent comments associated with exchanges or returns.
Column Data Type Constraint
comment_id varchar(40) not null
(primary key) The unique ID of this comment.
return_id varchar(40) not null
148 Appendix A. ATG Commerce Service Center Database Tables
Column Data Type Constraint
(primary key) The ID of the return the comment is associated with. References csr_exch
(id).
agent_id varchar(40) null
The profile ID of the agent who submitted the comment.
comment_data varchar(254) not null
The text of the comment.
creation_date timestamp null
The date and time when the comment was submitted.
version integer not null
The GSA version number of the repository item.
csr_exch_reasons
This table stores the return reason codes available to agents.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the return reason.
description varchar(254) not null
The description of the return reason.
csr_exch_item_disp
This table stores the returned item dispositions available to agents.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the disposition.
description varchar(254) not null
The description of the disposition.
Appendix A. ATG Commerce Service Center Database Tables 149
Column Data Type Constraint
upd_inventory tinyint not null
check (upd_inventory in (0,1))
Boolean indicating whether the inventory should be updated when an item
is returned with this disposition.
csr_return_fee
This table stores the processing fees associated with returns or exchanges.
Column Data Type Constraint
exchange_id varchar(40) not null
(primary key) The unique ID of the return or exchange. References csr_exch (id).
return_fee double precision not null
The amount of the return fee.
csr_exch_item
This table stores information about items that have been marked for return or exchange.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the item being returned.
commerce_item_id varchar(40) not null
The ID in the order repository of the commerce item being returned.
shipping_group_id varchar(40) not null
The ID in the order repository of the shipping group that the item was
shipped in. References dcspp_ship_group (shipping_group_id).
quantity_to_return numeric(19,0) not null
The quantity of the item being returned.
quantity_to_repl numeric(19,0) not null
The quantity of the item to replace.
150 Appendix A. ATG Commerce Service Center Database Tables
Column Data Type Constraint
reason varchar(40) not null
The ID of the return reason code for the item. References csr_exch_reasons
(id).
ret_shipment_req tinyint not null
check (ret_shipment_req in (0,1)
Boolean indicating whether return shipment of the item is required before
processing the refund or exchange.
bonus_refund tinyint not null
check (bonus_refund in (0,1))
Boolean indicating whether any bonus refund is associated with this item.
quantity_received numeric(19,0) not null
The quantity of the item that has been received through return shipment.
disposition varchar(40) null
The ID of the disposition code for the item. References csr_exch_item_disp
(id).
refund_amount double precision not null
The amount to be refunded for this item.
status varchar(40) not null
The return status of the item. Possible values: return_not_required,
awaiting_return, partial_return, returned.
exch_ref varchar(40) not null
The ID of the return that the item is associated with.
sugg_ship_refund double-precision not null
Suggested shipping refund amount.
actl_ship_refund double-precision not null
The actual shipping refund amount.
sugg_tax_refund double-precision not null
Suggested tax refund amount.
actl_tax_refund double-precision not null
The actual tax refund amount.
Appendix A. ATG Commerce Service Center Database Tables 151
csr_exch_repl_item
This table stores information about a replacement items in an exchange.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the replacement item.
sku_id varchar(40) not null
The SKU number of the replacement item.
quantity numeric(19,0) not null
The quantity of the replacement item.
csr_exch_repl_itms
This table associates exchanged items with their replacement items.
Column Data Type Constraint
exchange_item_id varchar(40) not null
(primary key) The ID of the exchanged item. References csr_exch_item (id).
repl_item_id varchar(40) not null
(primary key) The ID of the replacement item. References csr_exch_repl_item (id).
csr_exch_items
This table associates returned items with their returns.
Column Data Type Constraint
exchange_id varchar(40) not null
(primary key) The ID of the return. References csr_exch (id).
exchange_item_id varchar(40) not null
(primary key) The ID of the replacement item. References csr_exch_item (id).
152 Appendix A. ATG Commerce Service Center Database Tables
csr_exch_method
This table stores information about the refund associated with a return.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the refund.
type integer not null
The type of refund. 1=credit card; 2=store credit.
amount double precision null
The amount of the refund.
csr_exch_methods
This table associates refunds with their returns.
Column Data Type Constraint
exchange_id varchar(40) not null
(primary key) The ID of the return. References csr_exch (id).
exchange_method_id varchar(40) not null
(primary key) The ID of the refund. References csr_exch_method (id).
csr_cc_exch_method
This table stores information about credits applied to credit cards.
Column Data Type Constraint
exchange_method_id varchar(40) not null
(primary key) The ID of the refund. References csr_exch_method (id).
payment_group_id varchar(40) not null
The ID of the payment group the refund is being credited to.
Appendix A. ATG Commerce Service Center Database Tables 153
csr_sc_exch_method
This table stores information specific to store credits.
Column Data Type Constraint
exchange_method_id varchar(40) not null
(primary key) The ID of the refund. References csr_exch_method (id).
fixed_amount tinyint null
check (fixed_amount in (0,1))
The amount of the store credit.
bonus_credit tinyint null
check (bonus_credit in (0,1))
Boolean indicating whether a bonus was added to the store credit.
payment_group_id varchar(40) null
This field is not used.
sc_id varchar(40) null
The unique ID of the store credit.
ATG Commerce Service Center Logging Tables
ATG Commerce Service Center uses the following database tables to store audit logging information.
These tables are installed by the <ATG9dir>/CSC9.4/DCS-CSR/sql/
db_components/database-vendor/DCS-CSR_logging_ddl.sql script.
The tables described in this section are all used by the agent audit repository. The Nucleus component for this
repository is /atg/agent/logging/AuditRepository.
csr_grant_appease
This table stores log records about the granting of appeasements (store credits).
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the log record.
appeasement_id varchar(40) null
154 Appendix A. ATG Commerce Service Center Database Tables
Column Data Type Constraint
The ID of the store credit.
amount double precision null
The amount of the store credit.
csr_price_override
This table stores log records of manual price overrides.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the log record.
order_id varchar(40) null
The ID of the order containing the price override.
component_id varchar(40) null
The ID of the order component (item or shipping group) whose price was
overridden.
component_type varchar(40) null
The type of the order component whose price was overridden. Possible
values: commerceItem, shippingGroup.
old_price double precision null
The previous price of the item or shipping group.
new_price double precision null
The new price of the item or shipping group.
csr_order_event
This table stores log records about orders that have been modified.
Column Data Type Constraint
id varchar(40) not null
Appendix A. ATG Commerce Service Center Database Tables 155
Column Data Type Constraint
(primary key) The unique ID of the log record.
order_id varchar(40) null
The ID of the modified order.
amount double precision null
The total cost of the order.
csr_return_order
This table stores log records of returned orders.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the log record.
ret_req_id varchar(40) null
The ID of the return request.
repl_order_id varchar(40) null
The ID of the replacement order (for an exchange).
csr_recv_rtrn_item
This table stores log records of receipt of returned items.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the log record.
item_id varchar(40) null
The commerce item ID of the returned item.
quantity integer null
The quantity of the item that was returned.
156 Appendix A. ATG Commerce Service Center Database Tables
csr_claim_item
This table stores log records of the claiming of coupons, gift certificates, and store credits.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the log record.
claimable_id varchar(40) null
The ID of the coupon, gift certificate, or store credit.
claimable_type varchar(40) null
Type of item claimed (coupon, gift certificate, or store credit).
csr_ci_event
This table stores log records about changes to the quantities of items in orders.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the log record.
item_id varchar(40) null
The ID of the commerce item whose quantity was changed.
old_quantity integer null
The previous quantity of the item.
new_quantity integer null
The new quantity of the item.
csr_pg_event
This table stores log records about changes to payment groups in orders.
Column Data Type Constraint
id varchar(40) not null
Appendix A. ATG Commerce Service Center Database Tables 157
Column Data Type Constraint
(primary key) The unique ID of the log record.
pay_group_id varchar(40) null
The ID of the payment group that was changed.
update_type tinyint not null
The type of update performed. 0=modify; 1=remove; 2=add.
csr_split_sg
This table stores log records about splitting up items in orders among multiple shipping groups.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the log record.
src_ship_group_id varchar(40) null
The shipping group the item was moved from.
dest_ship_group_id varchar(40) null
The shipping group the item was moved to.
commerce_item_id varchar(40) null
The ID of the commerce item that was moved.
quantity integer not null
The quantity of the item that was moved.
csr_split_cc
This table stores log records about splitting up item costs among multiple cost centers.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of this log record.
src_cost_ctr_id varchar(40) null
158 Appendix A. ATG Commerce Service Center Database Tables
Column Data Type Constraint
The cost center that the item’s costs were moved from.
dest_cost_ctr_id varchar(40) null
The cost center that the item’s costs were moved into.
commerce_ident_id varchar(40) null
The ID of the commerce item whose costs were moved.
quantity integer not null
The quantity of the item whose costs were moved.
csr_sg_event
This table stores log records about changes to shipping groups in orders.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the log record.
ship_group_id varchar(40) null
The ID of the shipping group that was changed.
update_type integer not null
The type of update performed. 0=modify; 1=remove; 2=add.
csr_upd_props
This table stores log records about changes to properties of repository items.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the log record.
audit_id varchar(40) null
Appendix A. ATG Commerce Service Center Database Tables 159
Column Data Type Constraint
The ID of the log record this change is associated with. (For example, if the
change is to a shipping group, this value is the ID of the log record in the
csr_sg_event table.)
property_name varchar(40) null
The name of the property that was modified.
old_value varchar(255) null
The previous value of the property.
new_value varchar(255) null
The new value of the property.
version integer not null
The GSA version of the modified property.
csr_order_comment
This table stores log records about order comments submitted by agents.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the log record.
comment_id varchar(40) null
The ID of the comment.
csr_view_card
This table stores log records of agents viewing customers’ credit card information.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the log record.
cc_number varchar(20) null
160 Appendix A. ATG Commerce Service Center Database Tables
Column Data Type Constraint
The credit card number of the card that was viewed.
csr_oma_event
This table stores log records about order adjustments submitted by agents.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the log record.
man_adj_id varchar(40) null
The unique ID of the manual adjustment.
adjustment_type Integer not null
The type of adjustment.
update_type integer null
The type of update performed.
reason one-digit null
The reason for the adjustment
csr_schd_event
This table stores log records of scheduled events.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the log record.
sch_order_id varchar(40) null
The unique ID of the scheduled order.
update_type one-digit not null
The type of update.
Appendix A. ATG Commerce Service Center Database Tables 161
ATG Commerce Service Center Ticketing Tables
ATG Commerce Service Center uses the following database tables to store ticketing information.
These tables are installed by the <ATG9dir>/CSC9.4/DCS-CSR/sql/db_components/database-vendor/
DCS-CSR_ticketing_ddl.sql script.
The tables described in this section are all used by the ticketing repository. The Nucleus component for this
repository is /atg/ticketing/TicketingRepository.
csrt_grant_appease
This table stores ticketing records about the granting of appeasements (store credits).
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the record.
appeasement_id varchar(40) null
The ID of the store credit.
amount double precision null
The amount of the store credit.
csrt_price_overrde
This table stores ticketing records of manual price overrides.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the record.
order_id varchar(40) null
The ID of the order containing the price override.
component_id varchar(40) null
The ID of the order component (item or shipping group) whose price was
overridden.
component_type varchar(40) null
The type of the order component whose price was overridden. Possible
values: commerceItem, shippingGroup.
162 Appendix A. ATG Commerce Service Center Database Tables
Column Data Type Constraint
old_price double precision null
The calculated price of the item or shipping group.
new_price double precision null
The actual price charged to the customer for the item or shipping group.
csrt_order_event
This table stores ticketing records about orders that have been modified.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the record.
order_id varchar(40) null
The ID of the modified order.
amount double precision null
The total cost of the order.
csrt_return_order
This table stores ticketing records of returned orders.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the record.
ret_req_id varchar(40) null
The ID of the return request.
repl_order_id varchar(40) null
The ID of the replacement order (for an exchange).
Appendix A. ATG Commerce Service Center Database Tables 163
csrt_recv_rtrn_itm
This table stores ticketing records of receipt of returned items.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the record.
item_id varchar(40) null
The commerce item ID of the returned item.
quantity integer null
The quantity of the item that was returned.
csrt_claim_item
This table stores ticketing records of the claiming of coupons, gift certificates, and store credits.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the record.
claimable_id varchar(40) null
The ID of the coupon, gift certificate, or store credit.
claimable_type varchar(40) null
Type of item claimed (coupon, gift certificate, or store credit).
csrt_ci_event
This table stores ticketing records about changes to the quantities of items in orders.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the record.
item_id varchar(40) null
164 Appendix A. ATG Commerce Service Center Database Tables
Column Data Type Constraint
The ID of the commerce item whose quantity was changed.
old_quantity integer null
The previous quantity of the item.
new_quantity integer null
The new quantity of the item.
csrt_pg_event
This table stores ticketing records about changes to payment groups in orders.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the record.
pay_group_id varchar(40) null
The ID of the payment group that was changed.
update_type tinyint not null
The type of update performed. 0=modify; 1=remove; 2=add.
csrt_split_sg
This table stores ticketing records about splitting up items in orders among multiple shipping groups.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the record.
src_ship_group_id varchar(40) null
The shipping group the item was moved from.
dest_ship_group_id varchar(40) null
The shipping group the item was moved to.
commerce_item_id varchar(40) null
Appendix A. ATG Commerce Service Center Database Tables 165
Column Data Type Constraint
The ID of the commerce item that was moved.
quantity integer not null
The quantity of the item that was moved.
csrt_split_cc
This table stores ticketing records about splitting up item costs among multiple cost centers.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the record.
src_cost_ctr_id varchar(40) null
The cost center that the item’s costs were moved from.
dest_cost_ctr_id varchar(40) null
The cost center that the item’s costs were moved into.
commerce_ident_id varchar(40) null
The ID of the commerce item whose costs were moved.
quantity integer not null
The quantity of the item whose costs were moved.
csrt_sg_event
This table stores ticketing records about changes to shipping groups in orders.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the record.
ship_group_id varchar(40) null
The ID of the shipping group that was changed.
update_type integer not null
166 Appendix A. ATG Commerce Service Center Database Tables
Column Data Type Constraint
The type of update performed. 0=modify; 1=remove; 2=add.
csrt_order_comment
This table stores ticketing records about order comments submitted by agents.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the record.
comment_id varchar(40) null
The ID of the comment.
csrt_update_org
This table stores ticketing information about changes made to organization profiles.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the record.
updated_item_id varchar(40) Null
The ID of the organization profile that was modified.
csrt_orders
This table associates orders with tickets.
Column Data Type Constraint
order_id varchar(40) not null
(primary key) The ID of the order.
ticket_id varchar(40) not null
Appendix A. ATG Commerce Service Center Database Tables 167
Column Data Type Constraint
(primary key) The ID of the associated ticket.
csrt_oma_event
This table stores ticketing information about changes made to adjustment updates.
Column Data Type Constraint
id varchar(40) not null
(primary key) The unique ID of the record.
man_adj_id varchar(40) not null
The unique ID of the manual adjustment.
adjustment_type varchar(40) null
The type of adjustment.
update_type integer not null
The type of update.
reason integer not null
The number of the reason for the adjustment
csrt_schd_event
This table associates scheduled events with tickets.
Column Data Type Constraint
id varchar(40) not null
(primary key) The ID of the order.
schd_order_id varchar(40) not null
The ID of the scheduled order.
update_type integer not null
The type of update.
168 Appendix A. ATG Commerce Service Center Database Tables
Appendix B. CSC Access Rights Comparison 169
Appendix B. CSC Access Rights
Comparison
The following table displays the access rights for the CSC roles:
csr-
Ticketing
csr-
Order
csr-
Profile
csr-
Manager
Provides Access to
cmcAddProductByIdP x x x x Commerce tab’s Add
Product by ID panel
cmcBillingP x x x x Commerce tab’s
Billing panel
cmcCompleteExchangeP x x x x Commerce tab’s
Complete Exchange
panel
cmcCompleteOrderP x x x x Commerce tab’s
Complete Order
panel
cmcCompleteReturnP x x x x Commerce tab’s
Complete Return
panel
cmcConfirmExchangeP x x x x Commerce tab’s
Confirm Exchange
panel
cmcConfirmNewScheduleP x x Commerce tab’s
Confirm New
Schedule panel
cmcConfirmOrderP x x x x Commerce tab’s
Confirm Order panel
cmcConfirmReturnP x x x x Commerce tab’s
Confirm Return
panel
170 Appendix B. CSC Access Rights Comparison
csr-
Ticketing
csr-
Order
csr-
Profile
csr-
Manager
Provides Access to
cmcConfirmUpdateScheduleP x x Commerce tab’s
Confirm Updated
Schedule panel
cmcCrossSellP x x x x Commerce tab’s
Cross Sell panel
cmcCustomerCreateP x x x x Commerce tab’s
Create Customer
panel
cmcCustomerInfoP x x x x Commerce
tab’s Customer
Information panel
cmcCustomerP x x x x Commerce tab’s
Customer panel
cmcCustomerResultsP x x x x Commerce tab’s
Customer Results
panel
cmcCustomerSearchP x x x x Commerce tab’s
Customer Search
panel
cmcExchangeSummaryP x x x x Commerce tab’s
Exchange Summary
panel
cmcExistingOrderP x x x x Commerce tab’s
Existing Order panel
cmcExistingScheduledOrderP x x x x Commerce tab’s
Existing Scheduled
Order panel
cmcMoreCatalogsP x x x x Commerce tab’s
More Catalogs panel
cmcMorePriceListsP x x x x Commerce tab’s
More Price Lists
panel
cmcOrderHistoryP x x x x Commerce tab’s
Order History panel
cmcOrderResultsP x x x x Commerce tab’s
Order Results panel
Appendix B. CSC Access Rights Comparison 171
csr-
Ticketing
csr-
Order
csr-
Profile
csr-
Manager
Provides Access to
cmcOrderReturnsP x x x x Commerce tab’s
Order Returns panel
cmcOrderSearchP x x x x Commerce tab’s
Order Search panel
cmcOrderSummaryP x x x x Commerce tab’s
Order Summary
panel
cmcProductCatalogP x x x x Commerce tab’s
Product Catalog
panel
cmcProductViewP x x x x Commerce tab’s
Product View panel
cmcPromotionsP x x x x Commerce tab’s
Promotions panel
cmcPurchaseHistoryP x x x x Commerce tab’s
Purchase History
panel
cmcRefundTypeP x x x x Commerce tab’s
Refund Type panel
cmcRelatedOrdersP x x x x Commerce tab’s
Related Orders panel
cmcRelatedTicketsP x x x x Commerce tab’s
Related Tickets
panel
cmcReturnItemsP x x x x Commerce tab’s
Return Items panel
cmcReturnSummaryP x x x x Commerce tab’s
Return Summary
panel
cmcScheduleCreateP x x Commerce tab’s
Create Schedule
panel
cmcScheduledOrdersP x x x x Commerce tab’s
Scheduled Orders
panel
172 Appendix B. CSC Access Rights Comparison
csr-
Ticketing
csr-
Order
csr-
Profile
csr-
Manager
Provides Access to
cmcSchedulesP x x x Commerce tab’s
Order Schedules
panel
cmcScheduleUpdateP x x Commerce tab’s
Update Schedule
panel
cmcShippingAddressP x x x x Commerce tab’s
Shipping Address
panel
cmcShippingMethodP x x x x Commerce tab’s
Shipping Method
panel
cmcShoppingCartP x x x x Commerce tab’s
Shopping Cart panel
cmcSubmittedOrdersP x x x x Commerce tab’s
Submitted Orders
panel
cmcTicketHistoryP x x x x Commerce tab’s
Ticket History panel
commerceDesignTab x x x x Commerce Design
tab
commerceTab x x x x Commerce tab
CustomerAccountPanel x x x x Customer tab’s
Account panel
CustomerInformationPanel x x x x Customer tab’s
Information panel
CustomerOrderHistoryPanel x x x x Customer tab’s
Order History panel
CustomerResultsPanel x x x x Customer tab’s
Search Results panel
CustomerSearchPanel x x x x Customer’s tab
Search panel
customersTab x x x x Customer tab
CustomerTicketHistory
Panel
x x x x Customer tab’s
Ticket History panel
GlobalPanel x x x x Global panel
Appendix B. CSC Access Rights Comparison 173
csr-
Ticketing
csr-
Order
csr-
Profile
csr-
Manager
Provides Access to
HelpfulOpenByIDPanel x x x x Helpful panel’s Open
by ID panel
HelpfulRecentTicketsPanel x x x x Helpful panel’s
Recent Ticket panel
HelpfulTicketHistoryPanel x x x x Helpful panel’s
Ticket History panel
HelpfulTicketSummary x x x x Helpful panel’s
Ticket Summary
ResearchSolutionTickets
Panel
x x x x Global panel’s
Research Solution
Tickets panel
TasksAllTicketsPanel x x x x Task tab’s All Tickets
panel
TasksMyTicketsPanel x x x x Task tab’s My Tickets
panel
tasksTab x x x x Task tab
TicketActivityPanel x x x x Ticket tabs’ Activity
panel
TicketsCustomer
InformationPanel
x x x x Ticket tab’s
Information panel
TicketsResultsPanel x x x x Ticket tab’s Search
Results panel
TicketsSearchPanel x x x x Ticket tab’s Search
panel
TicketsSummaryPanel x x x x Ticket tab’s
Summary panel
ticketsTab x x x x Tickets tab
workspaceLogin x x x x Workspace Login
screen
svcCreateProfile x x Create Profile
permission
adjustPrice x Allows user to make
price overrides and
adjustments
174 Appendix B. CSC Access Rights Comparison
csr-
Ticketing
csr-
Order
csr-
Profile
csr-
Manager
Provides Access to
issueCredit x Allows user to issue
store credit
RespondComposeMessage
Panel
x Respond tab’s
Compose Message
panel
respondTab x Respond tab
For additional information, refer to the Setting Up Access Control (page 61) chapter.
Appendix C. CIM Configuration Components 175
Appendix C. CIM Configuration
Components
The ATG Configuration and Installation Manager script assists with the configuration of your ATG Commerce
Service Center (CSC) set up. The following components are configured.
Product Compatibility
CSC is installed using the common ATG platform and ATG Service Center CIM module. CSC can be installed in
conjunction with:
• ATG Knowledge
• ATG Self Service
• ATG Response Management
• ATG Service Center
• ATG Commerce
• ATG Search
Available Added Functionality
The following functionality add-ons can also be configured when installing CSC.
• ATG eStara Click to Connect
• Custom catalogs
• Data warehouse
• Price lists
176 Appendix C. CIM Configuration Components
• Publishing deployment and switching data sources for catalogs
• ATG Search Query Console
• Scheduled orders
Server Instances
The following server instances are configured when running CIM:
Server
Instance
Module List Required Data Sources
Agent STORE_MODULEFulfillment
DCS-
CSROPTIONAL_MODULESCSC_CUSTOMIZATIONS
JTDataSource
JTDataSource_production
Production JTDataSource
Data
Warehouse
(optional)
DCS-CSR.DW atg/reporting/datawarehouse/JTDataSource
atg/reporting/datawarehouse/loader/
JTDataSource
Add On Modifications
The following modifications occur to the server instances when using these optional add-ons:
Add On Server
Instance
Changes to Server Instance
Data Warehouse Data
Warehouse
Adds DCS.DW, Service.DW and DCS-CSR.DW DDLs
Adds DCS-CSR.DW to module list
This adds the Data Warehouse server instance listed above
ClickToConnect
(eStara)
Production Adds ClickToConnect and DCS.ClickToConnect DDLs
Adds DCS.ClickToConnect to module list
Adds account information to properties files
ClickToConnect
(eStara)
Agent Adds DCS-CSR.ClickToConnect to module list
Adds account information to properties files
Custom
Catalogs
Agent Adds customCatalog property to agent profile definition
You must set /atg/commerce/custsvc/util/
CSRConfigurator.defaultCatalogId to a valid catalog ID
Appendix C. CIM Configuration Components 177
Add On Server
Instance
Changes to Server Instance
Price Lists Agent Sets /atg/commerce/custsvc/util/
CSRConfigurator.usingPriceLists=true and /atg/commerce/
custsvc/util/
CSRConfigurator.usingSalePriceLists=true
MerchUI Publishing If using ATG Merchandising, CSC must be added to the
deployment topology as a deployment target. Additionally, if switching
data sources are enabled in Commerce, Publishing must be aware of this
to perform a switch on deployment
Scheduled
Orders
Agent Sets /atg/commerce/custsvc/util/
CSRConfigurator.usingScheduledOrders=true
Data Source Configuration
The following data source information is configured for each of the server instances.
JTDataSource for Agent
The following information is configured for the agent JTDataSource. The JTDataSource information for the
agent is stored in the DCS-CSR startup module.
SQL File
The SQL file used for the JTDataSource is <ATG9dir>/CSC9.4/DCSCSR/sql/db_components/
vendor/DCS-CSR_logging_ddl.sql.
Data Imports
The following files are imported using the DCS-CSR startup module:
Repository Imported File Versioned
/atg/svc/ui/framework/
ServiceFrameworkRepository
<ATG9dir>/CSC/DCS-CSR/
install/data/svc_framework.xml
Yes
/atg/svc/ui/framework/
ServiceFrameworkRepository_production
<ATG9dir>/CSC/DCS-CSR/
install/data/svc_framework.xml
No
/atg/userprofiling/
InternalProfileRepository
<ATG9dir>/CSC/DCS-CSR/
install/data/csrData.xml
No
/atg/svc/option/OptionRepository <ATG9dir>/CSC/DCS-CSR/
install/data/csrOptions.xml
Yes
178 Appendix C. CIM Configuration Components
Repository Imported File Versioned
/atg/svc/option/
OptionRepository_production
<ATG9dir>/CSC/DCS-CSR/
install/data/csrOptions.xml
No
JTDataSource for Production
The following information is configured for the production JTDataSource, which is the
JTDataSource_production data source in the agent instance. The JTDataSource information for production
is stored in the DCS-CSR startup module.
SQL File
The SQL files used for the JTDataSource are:
<ATG9dir>/CSC/DCS-CSR/sql/db_components/vendor/DCS-CSR_ddl.sql and <ATG9dir>/CSC/DCS-
CSR/sql/db_components/vendor/DCS-CSR_ticketing_ddl.sql
The following files are modified when using the ClickToConnect add-on:
Module SQL File
ClickToConnect <ATG9dir>/ClickToConnect/sql/db_components/vendor/
click_to_connect_ddl.sql
DCS.ClickToConnect <ATG9dir>/DCS/ClickToConnect/sql/db_components/vendor/
dcs_click_to_connect_ddl.sql
The following files are modified when using the Data Warehouse add-on:
Module SQL File
Service.DW <ATG9dir>/Service9.4/service/DW/sql/db_components/vendor/
svc_dw_ddl.sql
CIM File Configuration
When running CIM, the following files are configured using these default settings:
Production Server File Configurations
The following property file configurations are set for the production server.
Appendix C. CIM Configuration Components 179
Search Property File Configuration
The LaunchingService.properties file searchEngine and deployShare properties are installed on the
CSC production server.
The IndexingPeriodicService.properties file is set to enable=true to identify the production server as a
server that will be used by the indexing server to queue profile and order indexing requests.
The /atg/userprofiling/search/ProfileOutputConfig.incrementalUpdateSeconds and the /atg/
commerce/search/OrderOutputConfig.incrementalUpdateSeconds properties, which determine the
frequency for live indexing requests, are set to 5 seconds.
Note: If the server on which this is being configured is not the indexing server, set the
incrementalUpdateSeconds to -1. It is best to configure a non-DRP server as your indexing server.
ClickToConnect Property File Configuration
The /atg/clicktoconnect/Configuration.properties file is configured with the following information:
# Your eStara account IDaccountId=info_received_from_user_during_install# The eStara ClickToConnect usernameusername=info_received_from_user_during_install# The eStara ClickToConnect passwordpassword=info_received_from_user_during_install
Agent Server File Configurations
The following configuration changes are made on the agent server.
Search Property File Configuration
The LaunchingService.properties file searchEngine and deployShare properties are installed on the
CSC agent server.
The IndexingPeriodicService.properties file is set to enable=true to identify the management server
as a server that will perform queuing of index changes.
The /atg/userprofiling/search/ProfileOutputConfig.incrementalUpdateSeconds and the /atg/
commerce/search/OrderOutputConfig.incrementalUpdateSeconds properties, which determine the
frequency for live indexing requests, are set to 5 seconds.
Note: If the server on which this is being configured is not the indexing server, set the
incrementalUpdateSeconds to -1. It is best to configure a non-DRP server as your indexing server.
ClickToConnect Property File Configuration
The /atg/clicktoconnect/Configuration.properties file is configured with the following information:
# Your eStara account IDaccountId=info_received_from_user_during_install# The eStara ClickToConnect usernameusername=info_received_from_user_during_install
180 Appendix C. CIM Configuration Components
# The eStara ClickToConnect passwordpassword=info_received_from_user_during_install
The following key information is required by CSC to automatically authenticate an agent using a salted hash
passed through from eStara Wincare. The salt for the hash must be configured for CSC separately and must
match. For information on setting up the secret key in Wincare, refer to the Configuring eStara Click to Call (page
25) section.
Note: You must contact an eStara agent to set the corresponding secret key on the eStara side that matches
your agent server configuration. The CIM installation will neither obtain nor configure the eStara-side variables.
This information is stored in the /atg/svc/clicktoconnect/C2CTools.properties file:
# key that is included when calculating the hash value# for comparison to eStara computed value on the requestsecretKeyForHashCompare=info_received_from_user_during_install
Custom Catalogs Add On Configuration
The following information is configured if installing Custom Catalogs. The following information is stored in the
/atg/userprofiling/internalUserProfile.xml file:
<gsa-template> <item-descriptor name="agent"> <property name="catalog" property-type="atg.repository.nucleus. NucleusReferencePropertyDescriptor" data-type= "atg.repository.RepositoryItem"> <attribute name="component" value="/atg/commerce/custsvc/ environment/CSREnvironmentTools"/> <attribute name="property" value="currentCatalog"/> <attribute name="scope" value="global"/> <attribute name="repositoryName" value="/atg/commerce/ catalog/ProductCatalog"/> <attribute name="itemTypeName" value="catalog"/> <attribute name="typeName" value="string"/> </property> </item-descriptor></gsa-template>
The following information is configured in the /atg/commerce/custsvc/util/CSRConfigurator.
properties file:
defaultCatalogID=info_received_from_user_during_install
Price Lists Add On Configuration
The following information is configured if installing Price Lists. The following information is stored in the /atg/
commerce/custsvc/util/CSRConfigurator.properties file:
usingPriceLists=trueusingSalesPriceLists=true
Appendix C. CIM Configuration Components 181
Scheduled Orders Add On Configuration
The following information is configured if installing Scheduled Orders. The following information is stored in the
/atg/commerce/custsvc/util/CSRConfigurator.properties file:
usingScheduledOrders=true
182 Appendix C. CIM Configuration Components
Index 183
Index
Aaccess control, 61, 169
adjustments,manual price, 81
admin database, 9
agent
database, 9
facing server, 5, 6
schema, 14
architecture, 5
ATG Commerce
B2B, 7
with ATG CSC, 14
ATG Commerce Service Center
URL, 24
with ATG Commerce, 14
audit logging, 100, 104
Ccaching,disabling, 20
catalogs, 84
current, 82
custom, 85
custom, enabling, 85
default, defining, 85
product, 6
CIM, 10
configuration components, 175
clean partition searches, 22
Click to Call, 25
cloning
core classes, 74
extended, 76
order modification, 71
pipelines, 72
CSRConfigurator, 65
customer facing server, 5, 6
customer profile search, 17
customization, 65
renderers, 115
UI, 112
Ddata sources
agent facing, 6
connection, 12
customer facing, 6
switching, 6
database
admin, 9
agent, 9
core tables, 145
logging tables, 153
ticketing tables, 161
user accounts, 9, 9
ddl files, 10, 12
Ee-mail
notification, configuring, 66
order confirmation, 67
password, 66
templates, 67
EAR file
creating, 13, 24
deploying, 13
environment
global objects, 99
monitoring, 99
eStara, 25
agents, 27
and WinCare, 36
authentication, 39
call token, 30
clicktoConnectSave function, 29
CTI URL, 36
CTI, with, 37
customized popups, 32, 32
JavaScriptCallback rule, 29
landing pages, 39
links, 28, 30
orphaned sessions, disabling, 28
overview, 25
page instrumentation, 27
phone numbers, 27
pop ups, 32
requirements, 26
exchanges
configuring, 43
reason codes, 45
states, 43
Ffailover, 107
184 Index
form handlers, 108
forms, customizing, 125
Ggrids, customizing, 129
Hhover (see item detail page)
IIDGenerator, 15
importing
configuration data, 14
data, 13
data with ATG Commerce, 14
indexing, 17
indexing server, 17
installation
downloading files, 12
prerequisites, 3
item detail page, 143
JJava version required, 3, 9
JTDataSources, 6
customer-facing, 6
JTDatasources, 14
agent-facing, 12
customer-facing, 12
Kkeyboard
shortcuts, 108
shortcuts, mapping, 109
Llock managers
client, 16
on agent-facing server, 16
on customer-facing server, 16
server, 16
logs
agent activity, 104
audit, 102
database tables, 153
Nnavigation, keyboard, 108
notification, e-mail, 66
Oorders
fulfillment, 77
modifying, 71
scheduled, 49
scheduled, configuring, 68
submitted, 71
Ppanel
adding, 117, 120
customer management, customization, 119
definition, 119
panel stack
adding, 117
definition, 118
passwords, 66
payment group
credit card, 86
customization, 92
default, 92
gift certificate, 86
limiting amounts of, 97
store credit, 86
pipelines, 72
pop ups, eStara, 32
prerequisites, 3, 9
price list
configuring with scheduled orders, 50
current, 82, 83
default, 85
quick access, 84
pricing
locale, 85
manual adjustments, 81
orders and, 78
overview, 78
price lists, 79
promotions, 80
scheduled orders, 81
product catalog, 6
production (see customer facing server)
profiles
agent, 62
customer, 66
customer, e-mail configuration, 66
customer, password, 66
customers, pricing locale, 85
Rreason codes
exchanges, 45
returns, 45
refunds customization, 97
renderers
Index 185
components, 112
customization, 115
reporting
data collection, 52
enabling, 24
framework, 52
installing, 23
load pipeline, 55
repositories
configuring, 15
settings, 15
shared, 15
returned item dispositions, 47
returns
configuring, 43
item dispositions, 47
order states, 71
reason codes, 45
states, 43
rights
access, 61
with roles, 169
roles, 62
and access rights, 169
runAssembler command, 13
Sscenarios, 51
scheduled orders, 49
components, 69
schema
agent, 14
and ddl files, 10
creating, 12
searches
bulk indexing, 17
clean partition, 22
configuring environments, 22
configuring servers, 19
customer profile, 17
incremental, 17
Oracle catalog, 48
order, 17
server
agent facing, 5, 6
customer facing, 5, 6
production (see customer facing server)
shipping group
customization, 86, 87
default types, 87
electronic, 86
hard goods, 86
types, 86
SQL files, 10
Ttab
adding, 122
troubleshooting customization, 124
tables
core tables, 145
customizing, 129
logging, 153
ticketing, 161
ticket
activities, configuring, 105
disposition, 98
ticketing database tables, 161
UUI
customization, 112
modifying, 110
panel stack, adding, 117
186 Index