atg commerce service center installation and configuration … · 2013. 7. 25. · service center...

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.

http://www.atg.com/repositories/ContentCatalogRepository_en/manuals/Service9.2/apidoccsc/index.html


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


• 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.


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


database-vendor/DCS-CSR_ticketing_ddl.sql

Production


Script Run against this schema


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.


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:


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


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.


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.


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,


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:


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


/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


SearchSQLRepositoryEventServer.properties file:

componentPath=/atg/dynamo/server/SQLRepositoryEventServer_production

Edit the /localconfig/atg/search/service/SearchIdGenerator.properties file:

componentPath=/atg/dynamo/service/IdGenerator_production


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>


<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


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.


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


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


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


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.


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.


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


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


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.


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.


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.




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.



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


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)"/>

</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>



<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.



4. Ensure that the rule applies to both Customer and Agents, and that the rule is set to Enabled.


5. Enter the Link to Show. This is the link that you created in Step 9. For example, enter

StaticEarlyAdoptersLink.



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


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


• 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 = "";

/*


* 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.


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.


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


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.


/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



property. This component will land the agent on the catalog

browse main page.

For example:

URIMatches=/ondemand/subcategory.jsp?categoryId=


clicktoconnect/OrderView

LandingPageHandler



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


clicktoconnect/ProductView

LandingPageHandler



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=




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:


/atg/svc/clicktoconnect/

ProfileViewLandingPage

Identifies the values required to land on the

customer tab’s profile view page.

/atg/commerce/custsvc/clicktoconnect/

CategoryViewLandingPage


commerce tab’s catalog view page.


ProductViewLandingPage


commerce tab’s product view page.


OrderViewLandingPage

Provides the values needed to land on the

commerce tab’s order view page.


ScheduledOrderViewLandingPage

Identifies the values needed to land on the

commerce tab’s scheduled order view page.


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.


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.


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.


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.


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.


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


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.


• 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


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.


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


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,


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


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.



checkReturnExists

/atg/reporting/datawarehouse/process/

WarehouseItemExistsProcessor


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


custsvc/CreateReturnLineItemsProcessor


commerce.csr.CreateLineItemsProcessor

This processor creates an array or

the returned items map.

allocateOtherRefund


custsvc/OtherRefundAllocatorProcessor

.properties


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


custsvc/ReturnFeeAllocatorProcessor.

properties


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


custsvc/LineItemTotalAdjustments

Processor


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.



calculateTotal


custsvc/LineItemTotalRefundProcessor


commerce.ComputerLineItemTotal

Processor

This processor sums up all total

adjustments and item refund

items.

localCurrencyLookup


custsvc/LocalCurrencyLookupProcessor


commerce.CurrencyConverterProcessor

This processor converts local

currency to standard currency

values.

CurrencyConverter


custsvc/CurrencyConverterProcessor


commerce.CurrencyConverterProcessor

This processor converts shipping,

tax and other refunds, the return

fee, total adjustments and refunds.

dayLookup


custsvc/DayLookupPipelineProcessor


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


custsvc/TimeLookupPipelineProcessor


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


custsvc/CustomerLookupProcessor


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.



agentLookup


custsvc/InternalUserLookupProcessor


process.InternalUserLookupProcessor

$scope=global

This processor gets the agent ID

from the returnRequest.

agent.repositoryId. If the

agent is not found in the data



neither schemas, the processor will

return Unspecified.

returnSalesChannelLookup


custsvc/ReturnSalesChannelLookup

Processor


process.EnumeratedPropertyLookup

Processor

This processor looks up the return

channel ID in the data warehouse.

runReturnLineItemPipelineChain


custsvc/ReturnItemPipelineProcessor

This processor runs the return item

pipeline for each element of the

LineItems array.

returnItem lookupReturnSku


custsvc/SkuLookupProcessor



This processor looks up the SKU

ID for each return item in the data

warehouse.

lookupReturnProduct


custsvc/ProductLookupProcessor



This processor looks up the

product ID for each return item in

the data warehouse.

lookupReturnReason


custsvc/ReturnReasonLookupProcessor



This processor looks up the return

reason ID for each return item in

the data warehouse.



logReturnItem


custsvc/ReturnItemLoggerProcessor


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:


calls callLookup

/atg/reporting/datawarehouse/process

/svc/CallLookupProcessor.properties



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


WarehouseItemExistsProcessor


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


custsvc/CustomerLookupProcessor


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


neither schemas, the processor

will return Unspecified.

agentLookup


custsvc/InternalUserLookupProcessor


process.InternalUserLookupProcessor

$scope=global

This processor gets the agent ID

from the parameter map. If the

agent is not found in the data



neither schemas, the processor

will return Unspecified.



dayLookup





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






start time timestamp from the


lookup for the time of the time

stamp.

enddayLookup






end time timestamp from the


lookup for the end day of the time

stamp.

endtimeLookup






end time timestamp from the


lookup for the end time of the

time stamp.

totalTime This processor calculates the total

amount of call time in seconds.

callLogger


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


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:


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/


Formhandlers/CustomerProfileFormHandler component has several properties for managing e-mail

notifications:


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.


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


• 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.


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


Class Description

atg.commerce.csr.order.scheduled.

CSRScheduledOrderTools

Contains various helper APIs

Component:

/atg/commerce/custsvc/order/scheduled/CSRScheduledOrderFormHandler


CSRScheduledOrderFormHandler

Form handler used to create and update

schedules

Component: /atg/commerce/custsvc/order/scheduled/DuplicateAndSubmit


DuplicateAndSubmit

Form handler used by the Submit Now feature

Component: /atg/commerce/custsvc/order/scheduled/IsScheduledOrder


IsScheduledOrder

Servlet bean used to determine if an order is a

scheduled order template

Component: /atg/commerce/custsvc/order/scheduled/ScheduledOrderTableFormHandler


ScheduledOrderTableFormHandler

Form handler used to generate the content

displayed in the customer’s scheduled orders

panel

Component:

/atg/commerce/custsvc/order/scheduled/SchedulesTableFormHandler


SchedulesTableFormHandler


displayed in the scheduled order view’s

schedules panel

Component: /atg/commerce/custsvc/order/scheduled/SubmittedOrdersTableFormHandler


SubmittedOrdersTableFormHandler


displayed in the scheduled order view’s

submitted orders panel

Component: /atg/commerce/custsvc/order/scheduled/ActivateSchedule


LoadAndExecuteAction

Form handler used to active a schedule from the

schedule order view

Component: /atg/commerce/custsvc/order/scheduled/DeactivateSchedule


LoadAndExecuteAction

Form handler used to deactivate a schedule from

the schedule order view


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


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/


ValidateCloneFor

Edit

Validates the clone order after it has

been created.

initializeCloneEditState /atg/commerce/custsvc/


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.


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


RemoveEmptyShippingGroups

Executes the core


removes empty shipping

groups from the original

order.

removeEmptyPaymentGroups

FromOriginal


RemoveEmptyPaymentGroups

Executes the core


removes empty payment

groups from the original

order.

createImplicitRelationships

ForOriginal


CreateImplicitRelationships

Executes the core

commerce process

that creates implied

relationships between

commerce objects in the

original order.

setPaymentGroupAmounts

OnOriginal


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.


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.


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


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.


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:


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,\


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:


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.


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:


## 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.


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


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>

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">



<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>

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:


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.



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:


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:


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/


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'}">


<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>


</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


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:


Value1 Type [credit card type] – [last four

digits of card]

Visa - 2112

Value2 Expiration Date [card expiration year] / [card

expiration year]

11/12



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:


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:


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:


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:


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


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">


<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+=\


/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:


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


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


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.


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.


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


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/


ItemQuantityChanged /atg/commerce/custsvc/logging/


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/


RemovePaymentGroup /atg/commerce/custsvc/logging/


EditShippingGroup /atg/commerce/custsvc/logging/


RemoveShippingGroup /atg/commerce/custsvc/logging/


GrantAppeasement /atg/commerce/custsvc/logging/

GrantAppeasementRecorder


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.


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.


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


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.


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.



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;


_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.


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.


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.


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

# 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">



<valueof bean="pageData.product.id">

<valueof constant="prod10001">

</rule>

<rule op=eq>



<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.


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.


• 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.


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.


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"/>


<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.


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


"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>














</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.

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">

 <add-item item-descriptor="TabDefinition" id="WsMyNewTabDefinition"> <set-property name="appId" value="workspace"/> <set-property name="tabId" value="myNewTab"/>

<set-property name="titleKey" value="myNewTab.resource"/> <set-property name="resourceBundle" value="atg.commerce.csr.FrameworkResources"/> <set-property name="accessRight" value="GlobalPanel"/> <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>

 <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-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>


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="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.


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


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.


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


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


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



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


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


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


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.


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


• 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:


columns List containing all columns in display order



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


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:


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



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:



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


Column Configuration using an HTML Table

The properties for ColumnConfiguration using an HTML table are:


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:


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.


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


• 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:


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>


...

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.


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 $


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 $


field=lastModified

width=5em

resourceBundle=acme.resources.Resources

resourceKey=lastModifiedDate

defaultSort=descending

isVisible=true

dataRendererPage=/atg/commerce/custsvc/ui/tables/order/


LastModifiedRendererPage

4. In the sample application, create the properties file for the content page at /atg/commerce/custsvc/ui/

tables/order/

LastModifiedRendererPage.properties:


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:


<dsp:page>



<dsp:getvalueof var="colIndex" param="colIndex"/>


<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>

...


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:



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:


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 $

--%>


<dsp:page>



<dsp:getvalueof var="sortField" param="sortField" />


<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}"/>


<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.

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


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.


id varchar(40) not null

(primary key) The unique ID of the return.


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



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.


The unique ID of the agent.

csr_exch_cmts

This table stores agent comments associated with exchanges or returns.


comment_id varchar(40) not null

(primary key) The unique ID of this comment.

return_id varchar(40) not null



(primary key) The ID of the return the comment is associated with. References csr_exch

(id).


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.


The GSA version number of the repository item.

csr_exch_reasons

This table stores the return reason codes available to agents.



(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.



(primary key) The unique ID of the disposition.

description varchar(254) not null

The description of the disposition.



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.


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.



(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.



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.


csr_exch_repl_item

This table stores information about a replacement items in an exchange.



(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.


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.



(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).


csr_exch_method

This table stores information about the refund associated with a return.



(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.



(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.




payment_group_id varchar(40) not null

The ID of the payment group the refund is being credited to.


csr_sc_exch_method

This table stores information specific to store credits.




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).



(primary key) The unique ID of the log record.

appeasement_id varchar(40) null



The ID of the store credit.



csr_price_override

This table stores log records of manual price overrides.




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.







The ID of the modified order.


The total cost of the order.

csr_return_order

This table stores log records of returned orders.




ret_req_id varchar(40) null

The ID of the return request.


The ID of the replacement order (for an exchange).

csr_recv_rtrn_item

This table stores log records of receipt of returned items.




item_id varchar(40) null

The commerce item ID of the returned item.

quantity integer null

The quantity of the item that was returned.


csr_claim_item

This table stores log records of the claiming of coupons, gift certificates, and store credits.




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.





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.






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.




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.



(primary key) The unique ID of this log 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.


The quantity of the item whose costs were moved.

csr_sg_event

This table stores log records about changes to shipping groups in orders.




ship_group_id varchar(40) null

The ID of the shipping group that was changed.

update_type integer not null


csr_upd_props

This table stores log records about changes to properties of repository items.




audit_id varchar(40) null



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.


The GSA version of the modified property.

csr_order_comment

This table stores log records about order comments submitted by agents.




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.




cc_number varchar(20) null



The credit card number of the card that was viewed.

csr_oma_event

This table stores log records about order adjustments submitted by agents.




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.




sch_order_id varchar(40) null

The unique ID of the scheduled order.

update_type one-digit not null

The type of update.


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).



(primary key) The unique ID of the record.

appeasement_id varchar(40) null

The ID of the store credit.



csrt_price_overrde

This table stores ticketing records of manual price overrides.





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 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.





The ID of the modified order.


The total cost of the order.

csrt_return_order

This table stores ticketing records of returned orders.




ret_req_id varchar(40) null

The ID of the return request.


The ID of the replacement order (for an exchange).


csrt_recv_rtrn_itm

This table stores ticketing records of receipt of returned items.





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.




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.







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.




pay_group_id varchar(40) null

The ID of the payment group that was changed.

update_type tinyint not null


csrt_split_sg

This table stores ticketing records about splitting up items in orders among multiple shipping groups.




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.


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.




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.


The quantity of the item whose costs were moved.

csrt_sg_event

This table stores ticketing records about changes to shipping groups in orders.




ship_group_id varchar(40) null

The ID of the shipping group that was changed.





csrt_order_comment

This table stores ticketing records about order comments submitted by agents.




comment_id varchar(40) null

The ID of the comment.

csrt_update_org

This table stores ticketing information about changes made to organization profiles.




updated_item_id varchar(40) Null

The ID of the organization profile that was modified.

csrt_orders

This table associates orders with tickets.



(primary key) The ID of the order.

ticket_id varchar(40) not null



(primary key) The ID of the associated ticket.

csrt_oma_event

This table stores ticketing information about changes made to adjustment updates.




man_adj_id varchar(40) not null

The unique ID of the manual adjustment.

adjustment_type varchar(40) null

The type of adjustment.


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.



(primary key) The ID of the order.

schd_order_id varchar(40) not null

The ID of the scheduled order.


The type of update.

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


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


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


GlobalPanel x x x x Global panel


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


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


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


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


install/data/svc_framework.xml

No

/atg/userprofiling/

InternalProfileRepository


install/data/csrData.xml

No

/atg/svc/option/OptionRepository <ATG9dir>/CSC/DCS-CSR/

install/data/csrOptions.xml

Yes


Repository Imported File Versioned

/atg/svc/option/

OptionRepository_production


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.


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


# 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


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

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