e-Com ATG Framework and Components

ATG Framework and

Component

Pawan Modi
[email protected]

ATG FRAMEWORK &

COMPONENTS
ATG is the worldwide leader in the E-commerce solutions. This document describes ATG framework to
build e-commerce application.

ATG Page 1
 ATG Framework and Components

Table of Contents

ABBREVIATION 7

ATG 8
Introduction 8
ATG Architectures 8
Component Centric Model 8
Model View Controller MVC 8
Design Patterns followed in ATG 8

ATG Platform 9
ATG Dynamo Port Map 9
Module Dependencies 10

ATG Components 11
Dynamo Application Framework (DAF) 11
Dynamo Personalization Server (DPS) 11
Dynamo Scenario Server (DSS) 11
ATG Portal 11
ATG Commerce 12
ATG Content Administration (ATG Publishing) 12
ATG Merchandising 13
ATG Search 13
ATG CSC (Commerce Service Center) 13
ATG Outreach and Campaign Optimizer 13
ATG Control Center (ACC) 13
ATG Business Control Center (BCC) 14

Dynamo Application Framework (DAF) 15

Nucleus 15
Tag libraries 16
Dynamo Servlet Beans (Droplets) 16
Form Handlers 16
Repository API 16

Components 18
Create / Modify Components 18
Component Properties File 18
CONFIGPATH Environment Variable 19
Component Scope 19
Component Logging 19
GLOBAL.properties 19
Linking Property Values 19

ATG Page 2
 ATG Framework and Components

Repositories 21
Repository 21
Repository Item 22
Types of Repository in ATG 23
Item Descriptor 23
Repository View 27
Java Interfaces & Classes 27
Steps in Setting up a SQL Repository 28
Working with Repositories 29

Droplets (Dynamo Servlet Beans) 31

Advantages of Droplets 31
How to use Droplets in a JSP 31
Droplet Parameters 32
Important ATG Out-of-the Box Droplets 32
Steps in writing a Droplet 33
TargetingForEach 34
CategoryLookup, ProductLookup , SKULookup 34
ItemLookupDroplet 34
RepriceOrderDroplet, PriceEachItem, PriceItem 34

Form Handlers 35
Form Handler Beans 35
Form Handler Methods 35
Exception Handling in Form Handler 35
Displaying error messages on page 35
ATG Out-of-the Box Form Handlers 36
Example of Using a FormHandler 36
Steps in writing Custom Form Handler 36
Example of Custom Form Handler (Java Code) 37
Example of Custom Form Handler (JSP Code) 37
SimpleSQLFormHandler 38
RepositoryFormHandler 38
ProfileFormHandler 38
SearchFormHandler 38
/atg/userprofiling/B2CProfileFormHandler 38
atg.b2bcommerce.profile.B2BcommerceProfileFormHandler 38
atg.commerce.profile. CommerceProfileFormHandler 38
ShoppingCartModifier,ExpressCheckoutFormHandler, CartModifierFormHandler 38

ATG Controller Framework (Servlet Pipeline) 39

Request Handling by Servlet pipeline 39
DynamoHttpRequest and DynamoHttpResponse 39
ServletUtil 39
Types of Pipelines 40
Request Processing by DAF Servlet Pipeline 40

ATG Page 3
 ATG Framework and Components

Request Processing by DAS Servlet Pipeline 41

Customize Pipeline Servlet 42
InsertableServlet 42
Steps to Create InsertableServlet 43
DispatcherPipelineableServlet 44

ATG Scenarios (DSS) 45

Difference between Scenarios & Targeters 45
Slots 46

Dynamo Personalization Server (DPS) 47

Personalization 47
Message Content Processor 49
Content Management 50

ATG COMMERCE 53

ATG E-Commerce Functional Components 54

Profile Management 55
Profile Repository 55
Profile Form Handlers 55
B2C Profile Form Handler 56
B2B Commerce Profile Form Handler 56
Profile Tools and Property Manager 56
Create User Profile 57
Create Profile Group 57
Current Location Property 57

Catalog Management 58
Product Catalog 58
Extending default Product Catalog 58
Category Product and SKU 58
Catalog Navigation 59
Navigation History and Breadcrumbs 59
Custom Catalogs 60

Order Management 61
ATG Order Components (OTB) 61
ATG Order Java Interfaces 62
ATG Order Java Classes 63
Customizing OrderTools 65
Order Repository 69
/atg/userprofiling/Profile.transient Error! Bookmark not defined.

Pre-checkout Process 70

ATG Page 4
 ATG Framework and Components

Shopping cart Creation 70

Order Creation 71
Multiple orders creation for an user 71
Saving Modifying Repricing Orders 71
Extending Purchase Process 72
ChangedProperties Java Interface 72

Checkout Process 74
ExpressCheckout/Expedited Checkout 74
Complex checkout 74
Simple Checkout 74
Order Pipeline 75
Running a processor chain 76
User defined Processor Pipeline 76
Tags in Pipeline Definition File 77
Transaction Handling 77

Payment Process 78
Payment Pipeline chain 78
Order Fulfillment 79

Pricing and Promotions 80

PricingModel 80
Droplet for displaying price 80
ATG Pricing Services 81
Pricing Engine 81
Pricing calculators 81
Pricing Objects 81
Price Calculation Flow 82
Pricing Calculators 83
Pricing Engine implementation 83

Promotions 85
Attributes to manage promotions 85
eCoupon 86
Coupon FormHandler 86
Gift certificate 86
Gift certificate FormHandler 86

Extra Info 88
/atg/userprofiling/B2CProfileFormHandler 88
/atg/commerce/catalog/CatalogNavHistory 88
/atg/commerce/ShoppingCart 88
OrderManager 88
Order Repository 88
Profile Repository 89
Product Catalog 89

ATG Page 5
 ATG Framework and Components

sortProperties 89

ATG SEARCH ENGINE OPTIMIZATION (SEO) TECHNIQUES 91

Disclaimer 91

Repository 92
SEORepository 92
SitemapRepository 92

SEO Components 93

JumpServlet 96
JumpServlet Configuration 96

URL Optimization 97
JSP Coding 97
Component Configuration 97

Meta Tag Implementation 100

JSP Coding 100

Canonical URL 102

JSP Coding 102
Component Configuration 102

Sitemap Generation 104

Sitemap Configuration 104
Steps to Generate Sitemap 108

Appendix 109
Droplets 109
Form Handlers 111

ATG Page 6
 ATG Framework and Components

Abbreviation

DAS Dynamo Application Server

DAF Dynamo Application Framework

DSS Dynamo Scenario Server

DPS Dynamo Personalization Server

DRP Dynamo Request Protocol Server

GSS Global Scenario Server

LM Load Manager

CM Connection Module

RMI Remote Method Invocation

DCC Dynamo Control Center

SBS Session Backup Server

UDP User Datagram Protocol alternative protocol to TCP/IP, (usually used for broadcasting)

SNMP Simple Network Management Protocol, MIB packet services

ATG Page 7
 ATG Framework and Components

ATG
Introduction
ATG is the worldwide leader in the E-commerce solutions. ATG product suite has enabled the vendors
to enable their e-commerce commercial capabilities.

ATG Architectures
ATG follows architecture listed below.

Component Centric - The Dynamo Web applications are collected out of individual Java Bean
components, which are configured and linked together with .properties files.

MVC - Model View Controller architecture is a standard design pattern that separates an
application into three main components: the model, the view, and the controller.

Component Centric Model

Defines the basic architecture of a component, specified the structure of the interfaces and the
mechanisms by which it interacts with the container and other components. It also Provides guidelines
to create & implement components that can work together to form the application.

This model makes it possible for us to build Dynamo applications by configuring pre-built components
instead of writing a lot of Java code from scratch.

Model View Controller MVC

Model - The model contains the state of the application. It is not aware of the view or controller.

View - The view gives the presentation of the model. The view can access the model getters only.

Controller - The controller takes action on the user input and creates, sets the model.

Design Patterns followed in ATG

MVC2 in a Dispatcher View Strategy (a pull based MVC) used by Droplets.

MVC2 in a Service To Workers Strategy (a push based MVC) by formhandlers.

Dependency Injection or IoC (Inversion Of Control) used by nucleus to resolve inter

dependencies between components.

ATG Page 8
 ATG Framework and Components

ATG Platform
The ATG Platform and its suite of products is a flexible, Java-based development environment for
building personalized applications for the Web and other communication channels (e-mail messaging,
wireless devices, etc.). The platform and its related products, include Dynamo Application Server, ATG
Portal, ATG Commerce, ATG Content Administration, and the ATG Control Center.

ATG Dynamo Port Map

ATG Page 9
 ATG Framework and Components

Module Dependencies
ATG application often depends on other modules which are started automatically when your module is
started. These dependencies are declared in the module manifest file at location <module-
name>/META-INF/MANIFEST.MF.

The list show above will include DSS at a minimum. If our application uses facilities provided by other
application layers (e-commerce) then we will need to include those modules in the list as well. Note that
we only need to include the top-level module, all additional modules required by the top modules will
automatically be started.

E.g. If our application requires DSS, which requires DPS, then we need to specify only DSS not DPS.

ATG Page 10
 ATG Framework and Components

ATG Components
The ATG Platform includes the following core components:

DAF - Dynamo Application Framework (Foundation Layer)

DPS - ATG Personalization Module

DSS ATG Scenarios Module

Dynamo Application Framework (DAF)

The Dynamo Application Framework (DAF) is a foundation layer. DAF runs on top of (DAS) or leading
J2EE application server and supplies essential facilities for application development and deployment viz.

Nucleus

Repositories

Tag libraries

Droplets & Form Handlers

This portable framework is designed to run on the industrys leading J2EE application servers, including
ATGs own Dynamo Application Server (DAS), IBM WebSphere and BEA WebLogic.

Dynamo Personalization Server (DPS)

The Personalization module (DPS) provides tools for visitor profiling and content targeting, enabling to
deliver personalized content to customers according to their characteristics and preferences.

visitor profiling

content targeting

Dynamo Scenario Server (DSS)

The Scenarios module (DSS) adds advanced scenario-based personalization features to the ATG
Platform. Using the scenario editor, business managers can design, test, and fine-tune customer
management scenarios that track and respond to customer behavior. Business processes can be
exposed as workflows. Data analysis and reporting tools, including ready-made business chart
templates, are available for charting scenario data.

Scenario based personalization

ATG Portal
ATG Portal provides a customizable framework for building personalized Web portals for specific user
communities.

ATG Page 11
 ATG Framework and Components

A company, for example, might create separate portals for employees, customers, and partners, each
providing access to different content and services. The Portal Application Framework (PAF) is used by
developers to create and administer portals and the individual gears that render content and features (a
stock ticker or discussion forum, for example) within portal pages.

ATG Portal comes with a set of page template and baseline gears that you can use for your own portals.

ATG Commerce
ATG Commerce includes everything we need to build and manage personalized ecommerce Web sites.
ATG Consumer Commerce provides business-to-consumer (B2C) storefront development with following
features.

Product Catalog management

Profile Management

Shopping Cart and Checkout

Order Management

Pricing

Inventory

Customer Service

ATG Business Commerce adds support for following business-to-business (B2B) transactions.

B2B payment methods (purchase orders, requisitions)

Account-specific product catalogs

Price lists, multiple shipping/billing addresses etc.

ATG Content Administration (ATG Publishing)

ATG Content Administration (earlier known as ATG Publishing) is used for managing the content on the
production website. It provides a streamlined system for modifying and deploying content on your site.

The system maintains the versions for the changes made to publishable assets. It keeps track of multiple
versions of publishable assets (scenarios or catalog items, for example) within specific publishing
projects. Content administration provides following tools.

Workflow editor

Content Creation, Editing, Check-in Approval

Deployment to Production

ATG Page 12
 ATG Framework and Components

Using the workflow editor, you can define how each project moves through the various stages of the
publishing process i.e. content creation, editing, check-in, approval, QA and deployment on the live site.

ATG Merchandising
ATG Merchandising application runs on top of ATG Publishing and ATG Commerce. It provides a way to
Commerce Business users for creating and maintaining versioned content of various items like
ProductCatalog, Personalization targeters etc.

ATG Search
ATG Search is a leading search engine which lets users find in the information they wanted. The
response time of the search engine is very less. The features of ATG Search include.

Processes natural language queries

Supports faceted navigation in applications

Multiple language support

Industry-specific lexicons

Automated indexing features

Generating reports is easy using ATG Customer Intelligence

ATG CSC (Commerce Service Center)

ATG CSC (Commerce Service Center) is a web based application that also integrates a ticketing system,
which can be used by the Commerce Call center agents to manage customers, Orders etc. It enables the
sales and service agents to efficiently help customers over telephone, website, email or other means of
ATG Commerce.

ATG Commerce Service Center helps in increasing revenues and profits by turning the service center into
sales center. It provides a smooth customer service experience. ATG Commerce Service Center is
customer service application which can be customized and deployed.

ATG Knowledge and Response Management accumulate and provide CRM related information.

ATG Outreach and Campaign Optimizer

ATG Outreach and Campaign Optimizer are used by the marketing people to create promotions,
scenarios etc to track visitor behavior and tune the commerce system.

ATG Control Center (ACC)

ATG Control Center (ACC) is the integrated (stand-alone) user interface for the ATG Relationship
Management Platform and its supported products.

ATG Page 13
 ATG Framework and Components

The ACC provides application developers, page designers, site administrators, business managers, and
other members of your project team with point-and-click access to the tools they need for building and
maintaining ATG applications.

ATG Business Control Center (BCC)

The ATG Business Control Center is a browser-based interface that allows marketers and others senior
people to create and edit many of the elements required to maintain an ATG-based Web site. The
activities can be performed in the ATG Business Control Center are divided into the following general
areas.

ATG Content Administration

The ATG Business Control Center is the primary interface for performing ATG Content Administration
tasks, including the creation and deployment of Web site content.

Note: Content groups can be created via both i.e. ACC & BCC.

Management of ATG Personalization Assets

You use the ATG Business Control Center to create and manage the components that are responsible for
delivering personalized Web site content (content that changes dynamically for each site visitor).

These components include user segments, content targeters, and content groups.

Profiles Management
Management of the profiles required by ATG Business Control Center users, including their organization
and role assignments.

The ATG Business Control Center is also used as the starting point for launching several ATG applications
including the following

ATG Merchandising

ATG Outreach

ATG Service applications

ATG Page 14
 ATG Framework and Components

Dynamo Application Framework (DAF)

The ATG Platform is supported by a foundation layer called the Dynamo Application Framework (DAF)
that runs on top of our application server.

Our application server handles tasks like session management, load balancing, clustering, and SNMP
monitoring etc. But DAF supplies additional following facilities for application development and
deployment.

Nucleus
Nucleus is an ATG component container.

Nucleus is the central registry for the JavaBeans that contain our application-level logic.

It creates and configures Dynamo components and organizes them into a hierarchical
namespace so they can be referenced by other components.

By reading the various configuration files associated with each component, Nucleus figures out
what components to use in an application, what their initial properties are, and how they
connect to each other.

Nucleus allows developers to build applications in a component-oriented manner.

Nucleus is the mechanism that creates and configures new components, then gives these
components a place to "live" so they can be found by other components.

The components are stored in the Nucleus which is representing the components in a
hierarchical structure and the components are looked up using the request.resolveName(alias
name) method.

In Nucleus, every component has a unique name. Components are organized into a hierarchy,
similar to a file system. This results in component names such as
/atg/dynamo/service/Scheduler and gives Nucleus the ability to resolve relative names, such
as.../service/Scheduler. Furthermore, Nucleus components are JavaBeans, affording all the
advantages of the JavaBeans standard.

The Pages and Components task area in the ATG Control Center shows all of the components
currently registered in Nucleus (by module or by path) and provides templates to help we create
new ones, either from existing Dynamo classes or our own Java classes.

When it comes to configuring components for our application, we can use the built-in
Component Editor to specify initialization parameters and the way the components link
together. The ACC creates the necessary configuration files automatically.

DAF also provides a Web-based component browser, as part of the Dynamo Administration
interface that we can use to examine and modify components in a running Nucleus application.

ATG Page 15
 ATG Framework and Components

Tag libraries
Originally the presentation language used by the framework was JHTML. There are lots of
custom tags provided in JHTML to access the dynamo components.

When JSP become the presentation language for java, the DAF framework provides the DSP tag
library to access Nucleus components and render dynamic content from our Java Server Pages
(JSPs).

DAF also includes a Core tag library that provides generic tags for flow control, manipulating
data and handling transactions.

Dynamo Servlet Beans (Droplets)

Dynamo Servlet Beans are specialized Nucleus components that can be embedded in our JSPs to
display dynamic content.
Droplets are based on MVC2 Dispatcher View (pull based) design pattern.
Dynamo Servlet Beans minimizes the amount of Java code that has to appear in HTML and the
amount of HTML that has to be hard-coded into Java classes and also enables the developer to
take a Dispatcher View approach of MVC2 Design pattern.
As a result, Java programmers and page designers can work independently and applications are
easier to maintain.
DAF comes with a set of ready-made Dynamo Servlet Beans that you can use in your pages.

Form Handlers
Form handlers are specialized Nucleus components that can be embedded in our JSPs to do
form validation and based on the results do certain actions like inserting into database,
forwarding the user to some other JSP page etc.
Using Form Handlers is the way to achieve Service to Workers (push based) approach of MVC2
design pattern.
DAF comes with a set of ready-made Form handlers like ProfileFormHandler,
ShoppingCartModifier etc. that we can use in your pages either directly or customize them using
the extension points given.

Repository API
The Repository API (atg.repository.*) is a data access layer that defines a generic representation
of a data store.
ATG support SQL repository, LDAP repository, Composite repository & Versioned repository.
Whenever ATG applications needs to load, store, or query a data store, they make the
appropriate calls through this API. The API then accesses the underlying data storage device,
translating the API calls into whatever calls are needed to access that particular data store.
Implementations of the Repository API exist to access data stores such as relational databases,
LDAP systems, and content management systems.

ATG Page 16
 ATG Framework and Components

In addition, the Composite Repository feature enables us to consolidate multiple data sources
and make them available to our application as a single, queryable repository.
The Secured Repository Adapter provides fine-grained access control to repository item
descriptors, individual repository items, and even individual properties through the use of
Access Control Lists (ACLs).

ATG Page 17
 ATG Framework and Components

Components
Components in ATG are a public java class with appropriate properties with set/get methods.
Additionally a component comes with .properties file that specify the class name and the scope and also
any default values. The properties file also contains any dependency injections of other components.
This .properties file must be placed under CONFIGPATH of the ATG.

The name of the component is the full path name of the .properties file under the configpath starting
with a /. For example, /com/vam/firstbean. CONFIGPATH variable is computed dynamically during
startup based on the modules started, their order of startup and based on the entry in the
MANIFEST.MF file of every module started.

Use of components gives following advantages.

Code reusability

Reduced development time

Container independent

Entire application behavior can be changed by modifying one/some of the components.

Note: In ATG, a component have one of the 3 scopes i.e. Global, Session, Request.

Create / Modify Components

We can create / modify component and configure initial properties by

Using the eclipse ATG component browser plug-in.

Using ATG Control Center (ACC) browser.

Manually by editing the .properties file.

Using any of the above approach, we can browse components, set properties (single and multi-value),
link / unlink components.

Full component name are unique, containing folder names followed by simple component name,
separated by forward slashes like /atg/dynamo/service/SMTPEmail.

Component Properties File

Properties file is a text file and named with the component name (including full path) following by
.properties extension. Properties are name value pair. If the same property value is defined at different
level i.e. ATG local config level & application config level then value from application config level will be
taken. It is called configuration layering.

DPS/DSS ATG Local ConfigApplication Config

ATG Page 18
 ATG Framework and Components

Component properties file mainly contain class, description & scope information of a component. Class
is a name of java class with package. Description is a short description of component and scope tell
about the component scope.

ATG looks for component properties file in directories specified by CONFIGPATH environment variable.

CONFIGPATH Environment Variable

ATG looks for component properties file in directories specified by CONFIGPATH environment variable.
E.g. CONFIGPATH=<atgroot>\B2CAppearal\config

CONFIGPATH actually points to many folders and Nucleus reads entire CONFIGPATH left to right. So
every matching properties file is loaded.

If the same property value is defined in two files, the last value overrides previous values. It is called
configuration layering.

Component Scope
In ATG, a component can have any one of these scope.

Global (default) for everyone.

Session for individual session.

Request only to send response for a request.

Component Logging
Component can log information about their status. Logging can be done on per-component, per-module
or per-application basis. ATG support log levels i.e. error, warning, info, debug. Default log level is info.
Log files are generated <jboss>/server/atg/logs

Individual component can turn on/off their logging.

GLOBAL.properties
GLOBAL.properties is a special properties file, not associated with any specific component this is often
used to set logging levels for a set of components.

Linking Property Values

In a system containing many components, it is possible for several components to be initialized with the
same property values. If we configure (set value) these properties independently then this can lead to
the confusion for the administrator if the value is changed in one component, but not changed in the
other components. So we want to link the property of a component to other component.

ATG Nucleus can link the property of one component to the value of other component. To do this, we
need to append a ^ to the name of the property we want to set. Finally, enter the component name
and property name whose value is to be copied.

ATG Page 19
 ATG Framework and Components

For example if there is a second bean whose age property is dependent on firstbean age property, then
the properties file of second bean will look like shown below, where firstbean is a nucleus name relative
to secondbean.

ATG Page 20
 ATG Framework and Components

Repositories
ATG provides an easy to use and powerful object relational mapping (ORM) persistence framework. It
supports numerous databases, including Oracle and DB2, as well as popular open source databases such
as and MySQL. It uses reflection primarily to determine the java bean properties and does not need the
developer to code any POJO also.

Repository
The data access layer that defines a generic representation of a data store. Repositories access the
underlying data storage device through a connector, which translates the request into whatever calls
are needed to access that particular data store. Connectors for relational databases and LDAP
directories are provided out-of-the-box. Connectors use an open, published interface, so additional
custom connectors can be added if necessary.

A repository is a collection of repository items. Each repository connects to a single data store. But
application & subsystems in Dynamo can use different repositories or share the same repository.

The repository is not the data store itself instead, it is a collection of JavaBeans whose properties can be
found and stored in the data store. The mission of the repository is to provide a mechanism to retrieve
the data elements and a run-time representation of the available Meta information about each object.

Following are the main conceptual parts of the Repository API.

Repository Items - Each employee would have a corresponding repository item. Repository item
is corresponding to row in database table. Repository item is made of properties. These
properties correspond roughly to columns of a table

Item Descriptors - An employee item descriptor would specify all of the properties that an
employee repository item could possess.

Repository Queries - An application can build queries that return the appropriate employee.

ATG Page 21
 ATG Framework and Components

Repository Item
Repository items are like a JavaBeans. Their properties are determined dynamically at runtime. The
properties in a particular repository item depend on the type of item. One item might represent the user
profile (name, address, phone number) while another may represent the meta-data associated with a
news article (author, keywords, synopsis).

Each repository item is made of properties. These properties store the data that makes up a repository
item. Each property has a name, such as id, firstName, or lastName etc.

In the SQL repository, these properties correspond roughly to columns of a table. The properties
available to a type of repository item are defined in the repositorys item descriptors.

So the purpose of the Repository interface system is to provide a unified way for data access. For
example, developers can use targeting rules with the same syntax to find people or content.

Each repository item must have an identifier, which is called a repository ID. The repository ID must
uniquely identify the repository item from all other repository items of the same type. So each item
descriptor must specify the columns that act as the repository ID (which will usually be the same as the
tables primary key. If we dont define an id property in the item descriptor, then the id property must
use the default data-type, which is string.

For example, In the SQL repository, a repository item often corresponds to a row in a table. In the SQL
profile repository, each user profile is a repository item.

ATG Page 22
 ATG Framework and Components

Types of Repository in ATG

The following Repository models exist in ATG.

1. SQL Repositories - use ATGs Generic SQL Adapter (GSA) connector to perform a mapping
between ATG and data stored in a SQL database. It can be used to access content, user profiles,
application security information, and more.

2. LDAP Repository - Uses the Dynamo LDAP connector to access user data in an LDAP directory.

3. Composite Repository - provides a means for using more than one data store as the source for a
single repository.

4. Versioned Repositories - an extension of the GSA used in ATG Publishing. This is to maintain
versions of repository items.

Item Descriptor
Each repository item type is described by a Repository item descriptor (which has a one-to-one
correlation with RepositoryView). The item descriptor gives a name to the type, and also describes the
properties for that type. The name of each property is defined in the item descriptor, as well as the class
of the Java object used to represent that type (Integer, String, etc.). The item descriptors exposed by a
repository depend on a combination of the underlying data store and the configuration of the
repository.

For example, In the SQL repository, each database table might have its own repository item descriptor.
Or another alternative might join multiple tables into a single item descriptor.

Also Repositories can support multiple item descriptors. For example, a SQL repository instance that
supports a commerce application might have different item descriptors representing users, products,
product categories, orders, etc.

An item descriptor implements the atg.repository.RepositoryItemDescriptor interface and may subclass

atg.repository.ItemDescriptorImpl.

Item-Descriptor Relationships
One to One Represented by auxiliary tables.

One to Many Represented by multi tables

Many to Many achieved using an intermediate table.

The multi-column-name attribute ensures that the ordering of the multivalues are maintained.

The column specified by the multi-column-name attribute is used for multi-valued properties of data-
types array, map, and list and is not used for sets (which are unordered). For map type properties, the

ATG Page 23
 ATG Framework and Components

values in the column specified by the multi-column-name attribute must be a string. For list or array
type properties, these values should be an integer or numeric type, and must be sequential.

Xml-Combine
Xml combine tag is use to extend default catalog (product catalog).

xml-combine="replace"

xml-combine="remove"

xml-combine="append"

xml-combine="append-without-matching"

xml-combine="prepend"

xml-combine="prepend-without-matching"

Cascade attribute
The SQL repository uses the cascade attribute to better handle hierarchical properties with either the
item-type or component-item-type attributes. The cascade attribute can take one or more values i.e.
insert, update, or delete.

Cascade Insert
If a repository item has a property with the item-type attribute and the cascade="insert" attribute set,
then when the item is created following action executes.

A new item of the type declared by the item-type attribute is also created and

The property is set to point to the other item created.

The cascade="insert" attribute is typically used with cascade="update" and cascade="delete" so that
management of this item is completely automatic. The item is created, added, updated, and deleted
along with the parent item. The cascade="insert" attribute is ignored for properties that use
component-item-type.

Cascade Update
If a repository item has a property that refers to other items and that has the cascade="update
attribute set, then.

ATG Page 24
 ATG Framework and Components

When we call addItem(), any new (transient) items referenced by this property are added
automatically to the repository and

When we call updateItem, any referenced items that have been modified are automatically
updated. Any referenced items that are new (transient) items are added.

Cascade Delete
If a repository item has a property with the cascade="delete" attribute set, then when you remove the
repository item, any items that are referenced by the property will also be removed. Also, when you
remove a reference to this item, the item is automatically removed.

Special care must be taken in cascade delete in one-to-many relationships. Do not use cascade="delete"
in properties on the many side of the relationship that refer to items on the one side of the
relationship.

The item on the one side of the relationship cannot be deleted safely, since multiple items may be
referring to it.

For example, suppose you have an item descriptor named company with an employee property that
references many repository items defined by an employee item descriptor.

The employee item descriptor itself defines a company property. In this one-to-many relationship, the
employee property in the company item descriptor could use cascade="delete". But the company
property in the employee item descriptor should not use cascade="delete", since deleting one employee
item would then delete the company item that is referenced by the remaining employee items.

Item-Descriptor Hierarchy (Inheritance)

Item-descriptors also allow inheriting data from parent table. There exists an auxiliary relationship
between the parent and child item-descriptors. The parent item-descriptor specifies/restricts the child
item-descriptors that can inherit it by specifying the sub-type-property attribute. Fetching the child
repository item will automatically fetch data from the parent table as well.

Derived properties
In a SQL repository, we can have derived properties. This feature enables one repository item to derive
property values from another repository item or from another property in the same repository item.

Transient Properties
The SQL repository allows us to define transient attributes for a repository item. Transient attributes
are never stored or read from the persistent data store. They are readable and writable, but not
queryable.

ATG Page 25
 ATG Framework and Components

A transient property can be specified by defining a <property> tag that is not associated with any
database table, but which is instead a direct child of an <item-descriptor> tag.

Item Caches & Query Caches

Each item descriptor in a SQL repository has its own separate item cache and query cache. We size and
flush caches separately for separate item types. The item cache holds property values for repository
items. It is indexed by the repository item IDs. The query cache holds the repository IDs of items that
match particular queries in the cache. Query caching is turned off by default.

For example, suppose you have a query like this job = manager AND sal = 5555

If query caching is enabled, the first time this query is issued, the result set is retrieved from the
database and stored in the query cache. Then, the next time this same query is issued, the SQL
repository can retrieve the result set from the cache, rather than needing to access the database.

Cache Invalidation
Item cache entries are invalidated when that item is updated & affected queries are also invalidated. In
addition, whenever an item of a given item type is added to or removed from the repository, all queries
are invalidated in the query cache for that item descriptor.

Cache Modes
The SQL repository implements several different modes of caching. Which mode is to be chosen
depends on the nature of your Dynamo application.

No Caching (disabled)

Simple Caching - caching is handled separately in each VM, with no invalidation events to
synchronize updates from different server instances. By default, the SQL repository uses simple
caching. Simple mode is better if the application is running on only one JVM and is not clustered
across.

Locked Caching - read and write locks are used to synchronize the caches.

ATG Page 26
 ATG Framework and Components

Distributed Caching - caching with cache invalidation events.

By default, the SQL repository uses simple caching. To enable a different cache mode for an item
descriptor, set the cache-mode attribute in the item-descriptor tag of the repository definition file.

Note:

Simple mode is better if the application is running on only one JVM and is not clustered across.

If the ATG applications are deployed on a cluster of servers, then we have to go in for either
Locked caching or Distributed Caching.

For repositories like ProfileAdapterRepository, where at the most one server alone will be
handling the updates, it is better to use Locked caching because we have single server & many
modules wants to try operation at the same time.

Repository View
atg.repository.RepositoryView

If you do not have an exact repository ID, you can search for items in the repository through a
RepositoryView. Item descriptors and RepositoryViews often have a one-to-one relationship and often
have the same name. You can find out what views are available through the viewNames property of the
Repository component. This is useful if you need to build a system to navigate and view the entire
contents of a repository. The IDs for items in different item types might not overlap. There might be no
view that can return all items in the repository, but if there is, it is the default view. If you need to use
the default view, you can use the view named by the defaultViewName property. Alternatively, you can
create properties for your own services that allow you to explicitly name the view your code is
interested in using. After you have a name, you can retrieve that view through the RepositoryView
getView(String pName) method. From this returned object you can build and execute a query.

Java Interfaces & Classes

atg.repository.Repository
The atg.repository.Repository interface is the base definition of any repository implementation. This
interface provides methods to access RepositoryItems, RepositoryViews and ItemDescriptors,
corresponding to the three main elements of the repository.

atg.repository.RepositoryItem
The atg.repository.RepositoryItem interface is the immutable interface that represents an
element from a repository.

Each RepositoryItem is uniquely identified through its repositoryId property.

ATG Page 27
 ATG Framework and Components

After a repository item is created, but before it is added to the database, you can change its
repository ID by changing the value of the id property.

Once the item has become persistent, you can no longer change the ID.

atg.repository.RepositoryView

atg.repository.QueryBuilder
Sets of repository items can be gathered by queries, which you can build using the
atg.repository.QueryBuilder interface.

This QueryBuilder object can be obtained from the repository views queryBuilder property.

Once a query is built, each RepositoryView implementation translates the internalized data
structure into its native query language, for example SQL, and then return an array of repository
items that match the supplied query criteria.

Once a query is built from the QueryBuilder, it is executed via the various executeQuery
methods defined in the RepositoryView interface.

Above methods return either

an array of RepositoryItems, for elements that match the where clauses of the query,
or

null, if no elements could be found.

Steps in Setting up a SQL Repository

Write a Repository definition XML file following the DTD of the gsa-template tag.

Add the necessary item-descriptors in the XML file and map them to the appropriate tables.

Make the GSARepository java class into a global component by defining a .properties file and
configure the properties like DataSource, Definition file etc.,

Use the startSQLRepository command line tool to test out the repository and get the DDL
structure.

Create the necessary tables in the database.

ATG Page 28
 ATG Framework and Components

Add the repository to the ContentRepositories component, initialRepositories property if the

repository has to be started automatically during the ATG startup, or just leave it. The repository
component will be started when an application component accesses it, the first time.

Working with Repositories

Retrieving Item
We can retrieve items from the repository using the following methods.

Creating Item
We can create items using the following two methods.

Note Above methods creates a MutableRepositoryItem. This does not insert the item into the
Repository. The item exists only in the memory.

Adding Item
Once an item is created using create item method, we can turn it to a persistent repository item use the
addItem method.

Removing Item
Removing item persistently, just pass the ID and ItemDescriptor name of the item to the removeItem
method. The items property values will be deleted and will no longer be accessible from the repository.

Updating Item
The MutableRepository updates a repository item transactionally in three steps.

1. Fetch a mutable version of the repository item through the getItemForUpdate or

getItemsForUpdate methods. These methods return instances of MutableRepositoryItem.

ATG Page 29
 ATG Framework and Components

2. MutableRepositoryItem has a method setPropertyValue(String pPropertyName, Object

pPropertyValue) to update the property value. Use this method to change as many properties
as you wish.

3. Above changes will not be reflected in the repository until the final updateItem operation is
invoked. Save the changes with the updateItem method. This method extracts all the changes
required for the item and updates the item in the data store. Depending on how you have
configured transactional behavior, the update can be committed immediately, or the update
may happen automatically when the associated transaction commits. If there was any type of
error, a RepositoryException is thrown.

ATG Page 30
 ATG Framework and Components

Droplets (Dynamo Servlet Beans)

Droplet is a Servlet Bean to dynamically generate HTML from a Java Object. It minimizes the amount of
Java code that has to appear in HTML and the amount of HTML that has to be hard-coded into Java
classes.

DAF (Dynamo Application Framework) comes with a set of ready-made (out-of-the-box) Droplets that
can be used. The user can create their own droplets based on their need. They are referred as Custom
Droplets.

Advantages of Droplets
We can include multiple droplets in a single page.

Droplets can be nested

Parameters can be passed between different droplets. For examples - ForEach, Switch, IsNull,
IsEmpty etc.

How to use Droplets in a JSP

Import droplets using following statement.

Using droplets using following tag.

Passing parameters to droplet.

ATG Page 31
 ATG Framework and Components

Droplet Parameters
Input parameters

Passed to the servlet bean

Usually used by the java code to process

Output parameters

Set by the servlet bean

Used on the JSPs to display dynamic content

Open parameters

Open parameters contain the data that is rendered by the servlet bean.

Marked by dsp:oparam tags, and specify code to execute at different stages of servlet
processing.

Important ATG Out-of-the Box Droplets

Name Function
For Displays a single output the number of times specified
ForEach Displays each element of an array
Compare Displays one of a set of possible outputs, depending on the
relative value of its two input parameters
CurrencyFormatter Displays a numeric value as a currency amount, formatting it
based on the locale
ErrorMessageForEach Displays error messages that occur during a form submission
Format Displays one or more text values, formatting them based on
locale
IsEmpty Displays one of two possible outputs, depending on whether
its input parameter is empty
IsNull Displays one of two possible outputs, depending on whether
its input parameter is null
Name Function
Range Displays a subset of the elements of an array
Redirect Redirects the user to the specified page

ATG Page 32
 ATG Framework and Components

Switch Displays one of a set of possible outputs, depending on the

value of its input parameter
TableForEach Displays each element of an array, arranging the output in a
two-dimensional format
TableRange Displays a subset of the elements of an array, arranging the
output in a two-dimensional format
RQLQueryForEach Constructs an RQL query and renders its output parameter
once for each element returned by the query
RQLQueryRange Constructs an RQL query of a SQL database and renders its
output parameter for a selected subset of the elements
returned by the query

Steps in writing a Droplet

Write a java class extending the atg.servlet.DynamoServlet class.

Override the service() method and provide the logic there.

Identify the appropriate Input parameters that can be passed to droplet and the OPARAMS the
droplet will render and also the various output parameters the droplet will set in the request.

Write the BeanInfo class and define all the necessary parameters in that.

Make the droplet into a component using the ATG Component Browser.

Embed the droplet in a JSP page using the <dsp:droplet ..> tag and pass the necessary
parameters.

Us the OPARAM tags to mix the HTML content and the dynamic values returned by the droplet.

Example of Custom Droplet (Java Code)

ATG Page 33
 ATG Framework and Components

Example of Custom Droplet (JSP Code)

TargetingForEach
TargetingForEach droplet uses the RootCategories targeter to find root categories.

CategoryLookup, ProductLookup , SKULookup

Categories, products and skus can be displayed with the help of CategoryLookup, ProductLookup and
SKULookup droplets respectively.

ItemLookupDroplet

RepriceOrderDroplet, PriceEachItem, PriceItem

These droplets are used to display the price of the SKUs.

ATG Page 34
 ATG Framework and Components

Form Handlers
Form handlers are specialized nucleus components that embedded in JSPs to do form validation and
based on the results do certain actions like inserting into database, forwarding the user to some other
JSP page etc. The form handler checks the validity of the data, check for errors, and determines what
action to take (e.g., submits the data, direct the user to a different page, display an error message, etc.)

Following are the use cases of form handlers.

Displaying live value of the components property.

Dynamically setting values to components properties.

Direct interaction with SQL database e.g. Storing and retrieving information from database.

Example is ProfileFormHandler, ShoppingCartModifier etc.

Using Formhandlers we can associate various inputs to the nucleus components. User can create their
own Formhandlers based on their need. They are referred as Custom FormHandlers.

Form Handler Beans

These beans have their getters and setters. These are properties which can be set by the input elements
in a form. The form handler can evaluate the validity of the data and check for errors if any. The beans
can be use for output also.

Form Handler Methods

A form handler class must include one or more handler methods. A handler method is typically invoked
when the user clicks the submit button and handles the processing of the form. FormHandler can have
several methods depending on its purpose. E.g. FormHandler used to create a profile can have methods
for creating profile, modifying profile, deleting profile etc.

Exception Handling in Form Handler

As mentioned, FormHandler is used to handle errors and exceptions. These exceptions are stored in
following properties.

formError: A Boolean i.e. true if any errors occurred.

formExceptions: A vector of the exceptions that occurred when the form is processed.

propertyExceptions: A read-only property that returns a dictionary of subproperties, one for

each property set by the form. Any property that generates an exception, the corresponding
subproperty in the propertyExceptions contains that exception.

Displaying error messages on page

Check for the value of formError Boolean & render the error or exception using droplet i.e.
ErrorMessageForEach. This droplet is used to display the errors occurred during form Handling.

ATG Page 35
 ATG Framework and Components

ATG Out-of-the Box Form Handlers

Name Function
SimpleSQLFormHandler Works with form data that is stored in a SQL database.

RepositoryFormHandler Saving repository data to a database.

ProfileFormHandler Connect forms with user profiles stored in a profile repository. Creating,
modifying and deleting user profiles.
CartModifierFormHandler Used to process an order such as adding to cart, modifying cart etc.

QueryFormHandler Specifying properties to Search Engine. Also used to obtain refinements

from existing data.

Example of Using a FormHandler

Steps in writing Custom Form Handler

Create a java class extending the atg.droplet.GenericFormHandler base class.

Provide the appropriate handleXXX methods e.g. handleCreate(), handleUpdate() etc. Each
Handler method will be triggered by a corresponding dsp:input submit button from the JSP
page.

Provide either a Map data structure to hold the form data or provide individual fields with
appropriate set/get methods.

Write the validation logic inside the handler methods and return appropriate Boolean codes.

ATG Page 36
 ATG Framework and Components

Populate validation errors, if any, into the formExceptions Vector or proceed to do the business
logic.

Forward the user to the appropriate success URL.

Example of Custom Form Handler (Java Code)

In the following code sample, handleAddData() is handler method and name is handler bean. The
handler method will contain logic to do the validations and handling errors. The data is processed and
control is redirected to the successURL specified in the form.

Example of Custom Form Handler (JSP Code)

In following sample code, the input MyFormHandler.name is bean used to set the value after the form is
submitted. When user clicks on submit button the handleAddData() method of MyFormHandler Java
class get called which will process data and transfer control to the successURL specified in form action.

ATG Page 37
 ATG Framework and Components

SimpleSQLFormHandler
SimpleSQLFormHandler for working with form data that is stored in a SQL database.

RepositoryFormHandler
RepositoryFormHandler for saving repository data to a database.

ProfileFormHandler
ProfileFormHandler class to connect forms with user profiles stored in a profile repository.

SearchFormHandler
SearchFormHandler for specifying properties available to a search engine. You can also extend these and
other form handler classes to handle the specific needs of your application.

/atg/userprofiling/B2CProfileFormHandler

atg.b2bcommerce.profile.B2BcommerceProfileFormHandler

atg.commerce.profile. CommerceProfileFormHandler

ShoppingCartModifier,ExpressCheckoutFormHandler,
CartModifierFormHandler
These form handlers are used to manage the Shopping Carts.

ATG Page 38
 ATG Framework and Components

ATG Controller Framework (Servlet Pipeline)

ATG controller framework is used to handle the HTTP requests. The controller is called as servlet
pipeline while is formed by a sequence of separable independent steps. The sequence of the steps is
important because each step might depend on additional information about the request.

Major tasks of Servlet Pipeline include.

session tracking

page compilation

Request Handling by Servlet pipeline

Request handling can usually be broken down into a series of independent steps. Each step may depend
on additional information being available about the request, so order does matter. Each of the steps is
made by a single Nucleus service which implements the Servlet interface. The linked list of these servlet
called as request-handling pipeline.

Every request sent to the Dynamo server is dispatched to the servlet pipeline. The request is delivered
to the servlet at the head of the pipeline. The pipeline is started by Page filter and most requests
handled by Nucleus are dispatched to the PageFilter or DynamoProxyServlet. Each servlet in turn
performs its specific function on the request. Each servlet is also given a pointer to the next servlet in
the pipeline. When a servlet is done acting on the request, it can pass the request to the next servlet.
This linked-list of servlet is called the servlet pipeline. This provides the flexibility of customizing the
pipeline through configurable components.

DynamoHttpRequest and DynamoHttpResponse

The Dynamo server provides specific request, response pair called DynamoHttpServetRequest and
DynamoHttpServletResponse.

DynamoHttpServletRequest: atg.servlet.DynamoHttpServletRequest. This class implements

HttpServletRequest. It is a mutable class whereas HttpServletrequest is immutable.
DynamoHttpServletrequest provides methods that allow us to change the properties of the
request, such as setPathInfo or setPathTranslated.

DynamoHttpServletRequest object is created by DynamoHandler i.e. a first servlet in pipeline.

DynamoHandler create this object by wrapping generic HttpServletRequest object.

DynamoHttpServletResponse: There is also a corresponding

atg.servlet.DynamoHttpServletResponse that allows you to change properties of the
HttpServletResponse, such as the output stream and access its values, such as status code.

ServletUtil
This class (atg.servlet.ServletUtil) is used to import the information of Dynamo specific requests or
response. For example, to access the state object parameter, jsp should use following sample code.

ATG Page 39
 ATG Framework and Components

Types of Pipelines
There are two request-handling pipelines used by Dynamo.

DAF Servlet Pipeline - It is used to handle the JSP request. This pipeline is for customer
application jsp request.

DAS Servlet pipeline - It is used to handle JHTML request. Because JHTML is a proprietary
language, it relies on the page compiler provided in the DAS servlet pipeline to generate JHTML
into a servlet thats rendered as HTML by the application server.

Request Processing by DAF Servlet Pipeline

When a JSP page is requested, the DAF servlet pipeline runs through the set of servlet shown below.
Following figure also depicts the common servlets contained in the DAF Pipeline.

The application server follows the following path for processing the request.

1. When a user performs an action that prompts a response, the application server creates an
instance of the HttpServletRequest and HttpServletResponse.

2. Based on the directories and file extension of the requestURI, the application server uses servlet
and filter mappings defined in web.xml to determine the next resource to call.

3. By default, PageFilter is mapped to handle JSP requests. When the application server invokes
PageFilter, it checks the request and response for a reference to a Dynamo request and
response pair.

ATG Page 40
 ATG Framework and Components

4. The pair does not exist; PageFilter will start the DAF servlet pipeline by calling DynamoHandler,
the first servlet in the pipeline.

5. The DAF servlet pipeline will process through a series of servlets that modify the request and
response by extracting path information and providing session, user, and security information.

6. The last servlet in the pipeline is TailPipelineServlet. It is responsible for calling

FilterChain.doFilter(), which invokes the next filter defined in web.xml.

Note: ATG Business commerce pipeline includes additional components more than ATG Consumer
Commerce.

pageFilter is use only in DAF request handling pipeline. It is responsible to handle jsp pages. pageFilter
call an instance of DynamoHandler a first servlet in a pipeline. Now it is a responsibility of
DynamoHandler to generate DynamoHttpServletRequest wrapping generic HttpServletRequest.

Request Processing by DAS Servlet Pipeline

DAS is used to handle JHTML request. The pipeline runs through the set of servlet. As JHTML is a
proprietary language, it relies on the page compiler provided in the DAS servlet pipeline to generate
JHTML into a servlet thats rendered as HTML by the application server.

DynamoProxyServlet is used in DAS pipeline instead of pageFilter. DynamoProxyServlet make call to

DynamoHandler to start DAS pipeline.

The application server follows the following path for processing the request.

1. A call for a page in the dyn directory, which holds all JHTML pages, causes the application server
to invoke DynamoProxyServlet, which is responsible for starting the DAS servlet pipeline by
calling DynamoHandler.

2. The DAS servlet pipeline performs the same request and response handling tasks as the DAF
servlet pipeline.

3. One task common to both pipelines is the compiling of JHTML pages by PageCompileServlet,
one of the servlets in the pipeline.

4. By default, no filters are involved in request-handling process; if you create custom servlet
filters, they will be invoked before DynamoProxyServlet.

Note:-

Although DynamoHandler does the same thing in both pipelines but a different version of
DynamoHandler is used for each request type.

ATG Page 41
 ATG Framework and Components

PageFilter calls /atg/dynamo/servlet/dafpipeline/DynamoHandler to start the DAF servlet

pipeline for JSP requests.

DynamoProxyServlet calls /atg/dynamo/servlet/pipeline/DynamoHandler to start the DAS

servlet pipeline for JHTML requests.

The main difference between the DAS and DAF servlet pipelines is that the DAS servlet pipeline
automatically compiles the page from JHTML to Java, whereas the DAF servlet pipeline relies on the
application server to handle the complete page compilation process.

Customize Pipeline Servlet

All servlets in a pipeline implement PipelineableServlet interface of atg.servlet.pipeline package.
Servlets that implement PipelineableServlet have a nextServlet property that points to the next
component to invoke.

In order to write custom pipeline servlet, needs to implement an interface i.e. PipelineableServlet.
Create a component using this servlet. The components created by these servlets should be globally
scoped and configured to the pipeline.

You can write custom pipeline servlet by extending the atg.servlet.pipeline.PipelineableServletImpl

class. This class implements all Servlet methods, so we need to override the service method. This class
defines a property called nextServlet of type Servlet, which specifies the next servlet in the pipeline.
When your servlet finishes processing, it passes the request and response objects to the servlet
specified by this property, by invoking a method called passRequest.

The PipelineableServlet interface has two subinterfaces that provide additional mechanisms for
determining the next component to invoke.

InsertableServlet
Servlets that implement the InsertableServlet interface have an insertAfterServlet property that
enables the servlet to insert itself in a specific spot in the pipeline. The key advantage of this mechanism
is that it does not require modifying any existing servlets in the pipeline compared to
PipelineableServlet.

Example: if we want to insert a servlet i.e. Servlet1a, between two servlets i.e. Servlet1 & Servlet2 in the
pipeline.

ATG Page 42
 ATG Framework and Components

If Servlet1a implements PipelineableServlet, you can reroute the pipeline by changing the value of the
Servlet1.nextServlet property pointing to Servlet1a rather than Servlet2, and set Servlet1a.nextServlet to
point to Servlet2.

But if Servlet1a implements InsertableServlet, all you have to do is set Servlet1a.insertAfterServlet to

point to Servlet1, and Servlet1a will automatically be spliced into the pipeline right after Servlet1 and
before Servlet2.

Servlet1a is able to do this because it effectively sets its own nextServlet property to the value of
Servlet1s nextServlet property and rewrites Servlet1s nextServlet property to point to Servlet1.

Steps to Create InsertableServlet

Following steps involve creating & adding an InsertableServlet to the servlet pipeline.

1. Write a servlet e.g. MyServlet, extending InsertableServletImpl.

2. Define it as a component in the Nucleus hierarchy of this servlet. It does not really matter where
you put your servlet in the component hierarchy.

3. Set the insertAfterServlet property of your servlet to point to the path of the pipeline servlet
you want your servlet to follow in components property file.

4. For example, if you want your servlet to follow the DynamoServlet in the pipeline, use

5. Add the path to your servlet to the initialServices property of /atg/dynamo/servlet/Initial

ATG Page 43
 ATG Framework and Components

DispatcherPipelineableServlet
DispatcherPipelineableServlet interface provides a mechanism for conditionally branching the pipeline.
This interface includes a dispatcherServiceMap property that is a Map of possible servlets to invoke
next, depending on some condition.

key1, list1<servlets>

key2, list2<servlets>

If key1 is matched then servlets from list1 will be invoked in sequence.

If key2 is matching the condition then servlets from list2 will be invoked in sequence.

For example, the MimeTypeDispatcher servlet determines which servlet to invoke depending on the
MIME type of the request.

ATG Page 44
 ATG Framework and Components

ATG Scenarios (DSS)

DSS adds advanced personalization features such as customer management scenarios, data analysis and
reporting to the Dynamo framework. Scenarios are represented visually in the ATG Control Center by
flow diagrams that describe targeted customer interactions as a series of "if...then" triggers and
responses.

Example: If a customer registers, but doesn't log in within two weeks, then send them a reminder e-mail
offering a 10% discount toward their first purchase.

By analyzing the data collected from scenarios, we can fine-tune our business initiatives and the site's
overall design to best meet the needs of our customers.

Scenarios are event-driven. Event element defines what the site visitor does, an Action element defines
what the system does in response. A scenario anticipates and tracks the actions of the people who visit
our Web site and responds appropriately by tailoring the content of the site, offering price promotions,
or sending targeted e-mail messages.

Scenario server itself is event driven. Events in DAF are just JMS messages and therefore the scenario
server acts as a MessageSink. We can configure it to listen to various events (by default, it receives all
the standard Dynamo events).

When a scenario is created or modified in the ACC, its definition is saved in the scenario registry (located
at the Nucleus path /atg/registry/data/scenarios) as a file with the extension .sdl.

Difference between Scenarios & Targeters

S.NO Scenarios Targeters

1 Scenarios are triggered by events. Targeters are not event based.
The business rules we can set up through
If we want to personalize content as a targeters are more flexible in some cases than
result of a site visitor's doing something scenarios. For this reason, if we need to set up
specific (for example, logging in), use a highly complex rules to match content to
2 scenario. visitors, use targeters.

Scenarios use a feature called slots to

display dynamic content. Slots provide
some powerful advantages over targeters
(for example, we can set up empty slots
that generate their own requests for
3 content). Targeters dont use slots.
If we want to set up a long-term approach
to content and visitor management, use
4 scenarios.

ATG Page 45
 ATG Framework and Components

Slots
Slots are Nucleus components that can be used to display and manage dynamic content on Web site.
Targeting servlet beans are used to include slots in site pages and scenarios are used to fill them with
content. Slots are more powerful and flexible than targeters. Example, slots have better caching
capabilities than targeters, which can make displaying content faster.

Slots have better caching capabilities, which can make displaying content faster. Scenarios use slots to
manage the delivery of dynamic content. For example, scenarios allow us to set up an empty slot that
generates its own request for content when a site visitor displays the page.

The process of creating and setting up a slot has the following steps.

1. Create the slot component.

2. Add an appropriate targeting servlet bean (for example, TargetingForEach) to the page or pages
where you want the slot to appear. In the Targeter property of the bean, specify the slot
component.

3. Create a scenario that specifies the content you want to display in the slot and defines the
circumstances in which the content appears.

ATG Page 46
 ATG Framework and Components

Dynamo Personalization Server (DPS)

ATG provides a way to match page content to individuals based on their needs and preferences. DPS
provides a full set of customizable tools for displaying targeted information. ATG Personalization
Module (DPS) provides features that are specifically designed to support Web site personalization,
which is the process of displaying different content to each site visitor depending on his or her
preferences and requirements.

Ideally, a Web site should recognize that we are looking at a particular category of information, and
show the related products, services, and information for that category. This concept called as
personalization. Personalized Web sites customize the behavior, content, and presentation of the site
to fit each visitor's characteristics and preferences. Some Web applications explicitly segment their users
into several affinity groups (such as visitors and members, or investors and brokers), and associate
different content with each group of users.

Why personalization is important?

When the World Wide Web was first developed, one big problem was trying to find valuable information.
There was not much content published, and searching for the right piece of information was difficult. To
make finding the sparse information easier, companies such as Yahoo started creating indexes of all the
available content, and Web sites started including site maps among their pages.

Most Web sites today have their own search engines, because the amount of content on even a single
site is too vast to navigate by means of a site map.

Personalization
ATG Personalization lets you customize content for specific users and events, primarily through two
mechanisms.

Content targeters that match content to specific users.

Slots that display their content in the context of certain events, or scenarios.

DPS Repository
Dynamo SQL Profile Repository - It is pre-configured default repository for DPS. Using this, we can
store, modify and query user profile data in a SQL database. Example is
/atg/userprofiling/ProfileAdapterRepository.

Dynamo LDAP Profile Repository - Using this, we can store, modify and query user profile data in LDAP
(Lightweight Directory Access Protocol) directory.

Content Repository - A content repository is a collection of content items managed by a single system
such as a relational database, file system, or third-party content management system. A content

ATG Page 47
 ATG Framework and Components

repository typically serves as a source of content items to be displayed to a user, either directly or as an
element in a page.

Note: Since the GSARepository class implements both the atg.repository.Repository interface and the
atg.repository.content.ContentRepository interface. So a repository can contain multiple repository item
types. So a single repository can contain both content repository items (arranged in a hierarchical
structure with folders that can contain repository items and other folders) and non-content repository
items (arranged in a flat structure).

A SQL content repository must contain following things.

One and only one item descriptor that defines repository items that act as folders (the folder
item descriptor) and

One or more item descriptors that define content repository items (the content item
descriptors).

DPS Form Handler

This form handlers contains the handler methods to handle the user login, registration, updation etc.
Also there are extension methods like preCreateUser(), postCreateUser(), preLoginUser(),
postLoginUser() etc., provided.

/atg/userprofiling/ProfileFormHandler - process form input and updating user profiles.

atg.scenario.userprofiling.ScenarioProfileFormHandler - If ATG is started with DSS then

ScenarioProfileFormHandler is an implementation class.

User Profile Management

When a person visits our Web site, DPS creates a profile for him or her (based on a profile template) and
stores it in a database. This profile contains a list of properties that describe the person's characteristics,
such as the name he or she entered in a registration form (a self-reported, or explicit, attribute) or the
date of the person's last login (a system-generated, or implicit, attribute). All profiles track the same
attributes, only the values vary from user to user.

DPS makes profiles persistent by storing them in a database. DPS includes two implementations of the
Dynamo Repository API for accessing stored profile data.

Keeping track of profile attributes makes it possible to segment site visitors into target audiences called
profile groups. Business managers create profile groups by defining business rules in the Targeting >
Profile Groups window of the ATG Control Center. Once we create a profile group, we can use it to
define our targeting rules and scenarios (if we have DSS installed).

ATG Page 48
 ATG Framework and Components

Profile Properties
The profile contains properties that describe the person's characteristics. There are two kinds of profile
properties. Usually, the system updates profile properties automatically. We do not have to change
them. But Control Center provides options that let us view the profiles in the repository. We can also
use them to add, edit, and delete profiles if necessary.

Explicit Properties Explicit properties are provided by site visitors when they fill registration form to
become a member of your site. Examples of explicit properties are a person's name and address.

Implicit Properties - Implicit properties are information that the system gathers about visitors by
tracking their behavior at your site. Example is a list of recently browsed Web pages is an implicit
property.

Message Content Processor

MessageContentProcessor is responsible for actually setting the e-mail message content given the
rendered message body. TemplateEmailInfoImpls contentProcessor property points to an object of
MessageContentProcessor. MessageContentProcessor is an abstract class. The Personalization module
includes two concrete subclasses of MessageContentProcessor i.e. SimpleContentProcessor and
HtmlContentProcessor. We can also implement our own content-processing scheme by creating a
subclass of MessageContentProcessor that implements all of its methods.

SimpleContentProcessor
This doesnt do any processing on the passed in message content, but simply uses the content as is to
set the javax.mail.Message content. The MIME type of the content in the Message is specified by the
services contentType property. Example, if contentType is text/html the rendered page is sent as
HTML and if the contentType is text/plain it will be sent as simple text (no word wrapping).

HtmlContentProcessor
HtmlContentProcessor a more sophisticated implementation of MessageContentProcessor. This does
the following jobs.

1. Takes in content of type text/html.

2. Optionally, converts it into content of type text/plain.

3. Performs word wrapping on the plain text version of the content.

4. Determines whether to send the Message content as text/html, text/plain, or

multipart/alternative with text/plain and text/html parts.

ATG Page 49
 ATG Framework and Components

Content Management
The term content refers to discrete units of information (a news article or a banner image, for example)
available for display to Web site visitors, either directly or as an element in a Dynamo Server Page. Each
unit of content, or content item, is associated with a particular type of media (an HTML or XML file, a
GIF file, a PDF document, etc.) and has meta-data that describe its characteristics.

Content data is also stored in searchable repositories. A content repository is a collection of content
items managed by a single system such as a relational database, file system, or third-party content
management system.

Dynamo includes three implementations of Content Repositories.

SQL Content Repository

The SQL Content Repository provides access to content stored in a SQL database.

HTML Content Repository

The HTML Content Repository provides access to HTML files stored in a file system. HTML content
repository can be created from ACC with repository component and its associated DataStore,
HTMLItemDescriptor, and RepositoryPropertyDescriptor components.

XML Content Repository

The XML Content Repository provides access to XML files stored in a file system. The ACC includes a
wizard to help us create components that make up an XML Content Repository, including the
XMLRepositoryService component and its associated XMLDataStore, XMLItemDescriptor, and
RepositoryPropertyDescriptor components.

Once we set up a content repository, we can run queries against meta-data attributes to search for and
manage particular content items. We can also run targeting operations against the content attributes to
match content items with visitor profiles.

Similar to profile groups, we can organize content items into logical groupings called content groups by
defining business rules in the Targeting > Content Groups window of the ATG Control Center. Once we
create a content group, we can use it to define our targeting rules and scenarios (if we have DSS
installed).

Content Targeter & Targeting

Targeting is the process of displaying content items to a particular user, at a particular time, in a
particular context. Content targeters that match content to specific users.

Content targeters are the business rules created using the ACC. In the DPS rule-based system, business
managers create rule sets that control how content is displayed on the Web site. Business rules define
the content that we show to each profile group.

ATG Page 50
 ATG Framework and Components

Content targeter relates the content group with the profile group.

To display targeted content, site must include content targeters that define the rules that determine
which users see what content. You can create targeters through the Content window of the Control
Center.

ATG Personalization includes five targeting servlet beans

TargetingForEach displays all of the items returned by the targeter.

TargetingFirst displays the first n items, where n is a number you specify.

TargetingRange displays a range of items, such as the third through the seventh.

TargetingRandom displays n items chosen randomly.

TargetingArray

The first four of these servlet beans perform fundamentally similar operations. Each one uses a
targeter to gather a set of items from a content repository, and renders the content items on the
page. They differ only in whether they display all of the items returned by the targeter, or just a
specific subset.

We can disable this behavior for any targeting servlet bean by setting one or both of the following
parameters in the servlet.

Note - If we have ATG Scenarios, we can use scenarios instead of targeting rules to control the content
that we display to each profile group.

ATG Page 51
 ATG Framework and Components

Steps Involve in Personalization

Once we have planned our approach to the relationship between site visitors and content, we use the
Control Center to Create profile groups, group similar content items together, match content groups to
profile groups & determine the visitor behavior that we will track and use to update profiles.

Use following steps to personalize website.

Set up visitor profiles.

Create profile groups.

Set up content items.

Group content items together

Match content items with targeted audiences (profile groups).

Track visitor behavior.

Preview the site

Analyze data and fine tune the personalization

ATG Page 52
 ATG Framework and Components

ATG Commerce
ATG Commerce module provides the foundational packages for online store. It handles pricing,
inventory, fulfillment, merchandising, targeted promotions, and customer relationships. ATG supports
both B2C by ATG Consumer Commerce and B2B by ATG Business Commerce.

ATG support following features for Consumer Commerce.

Profile management

Product Catalog

Product catalog display templates.

Catalog navigation & Product/SKU Comparison.

Setting pricing models.

Shopping carts, multiple shopping carts for a user.

Orders management like canceling, viewing orders.

Inventory management

Merchandising(promotions, coupons, gift certificates)

Integration with Payment gateways and TAX systems.

Modular code execution using pipelines

ATG support following features for Business Commerce.

Cost Centers to track internal costs.

Exporting an Order as XML.

Scheduled order for regular buyers.

Order approvals by other higher authorities.

Custom catalogs for different users from different organizations.

Volume Pricing & Tiered pricing

ATG Page 53
 ATG Framework and Components

ATG E-Commerce Functional Components

ATG is not just a framework but a package where common e-commerce features are provided out of
box. Developers can use these features in their e-com application with minor configurations. ATG
support following e-com functional components.

Profile Creation and Management.

Product catalog services and Navigation

Pre-checkout/Purchasing process like Shopping carts

Merchandising features like cross-sell, up-sell etc.

Checkout and Payment Processing.

Order Fulfillment

ATG Page 54
 ATG Framework and Components

Profile Management
Profile management is the extension of Personalization functionality. The following are the extensions
of personalization.

Profile Repository

Profile Form Handler

Profile Tools and Property Manager

Profile Repository
Describes the attributes that ATG Commerce adds to the user Item Descriptor to support gift lists, wish
lists, promotions, address books, credit card collection and other minor features.

The Personalization modules Profile Repository is an instance of the Generic SQL Adapter. It is located
in /atg/userprofiling/ProfileAdapterRepository. The Personalization module defines a base user Item
Descriptor in it. This user has many general attributes defined, such as first and last name, e-mail
address, date of birth and home address. It adds several attributes to the user Item Descriptor to
support gift lists, wish lists, promotions, address books, credit card collection and other minor features.

Additionally it also provides properties such as

Promotions based properties like activePromotions, usedPromotions etc.

Address based properties like shipping Address, billingAddress etc.

Payment based properties like CreditCard number, type, expirationYear etc.

List features like wishList, giftLists etc.

Shopping preferences like allowPartialShipping, allowExpressCheckout etc.

Profile Form Handlers

The ATG Commerce profile form handler (atg.commerce.profile.CommerceProfileFormHandler) is a
subclass of atg.userprofiling.ProfileFormHandler for commerce specific operations.

The following operations are performed by overriding the addPropertiesOnLogin, postCreateUser and
postLoginUser methods from the ProfileFormHandler.

1. An anonymous user can accumulate promotions in their activePromotions attribute. During

login, the anonymous users active promotions are copied into the list of active promotions of
the persistent user.

ATG Page 55
 ATG Framework and Components

2. During the registration and login process, any shopping carts (Orders) created before logging in
are changed to be persistent. If the users persistent profile contains any old shopping carts
(Orders in an incomplete state), these shopping carts are loaded into the users session.

3. After log in, the PricingModelHolder component is reinitialized to cache all the promotions that
the persistent user has accumulated during previous sessions.

B2C Profile Form Handler

It is extending user Profile form handler for B2C Commerce. Class
/atg/userprofiling/B2CProfileFormHandler extend from
atg.commerce.profile.CommerceProfileFormHandler class and is injected the component
CommerceProfileTools to perform most of the commerce profile related activities.

The /atg/userprofiling/B2CProfileFormHandler component is used to handle user specific operations

like user login, registration, logoff etc. This also contains a Map property by name editValue that holds
extra properties like shippingAddress etc.

The B2CProfileFormHandler also provide handler methods to check up creditcards for their format and
there is a converter to print the Credit card number masked.

We can use the Profile.transient property to check up whether the user is logged in or not and act
accordingly.

Note: Any custom profile property that is added by us, must be handled in our FormHandler component
which will extend the B2CProfileFormHandler. The userProfile.xml can be extended to add more
properties.

B2B Commerce Profile Form Handler

ATG Commerce provides a class atg.b2bcommerce.profile.B2BCommerceProfileFormHandler class that
extends the CommerceProfileFormHandler and this is available under B2BCommerce for use.

In B2B, it is extended to include the concept of addition or removal of CostCenters for B2B sites.

Profile Tools and Property Manager

Profile tools & property manager provide additional methods to access commerce specific profile
properties such as shipping and billing addresses and credit card information. Also describes the
extensions related to the ATG Commerce Property Manager, which provides additional access to profile
property names specific to Commerce customers that are used by Commerce Profile Tools.

ATG Commerce profile tools

Class atg.commerce.profile.CommerceProfileTools is a subclass of atg.userprofiling.ProfileTools. It
provides additional methods to access commerce specific profile properties such as shipping and billing
addresses and credit card information.

ATG Page 56
 ATG Framework and Components

Example: The shipping addresses are managed by the Commerce Profile Tools component. This
extension of the tools component provides methods to create, delete and update profile repository
shipping addresses as well as to retrieve all shipping addresses.

ATG Commerce Property Manager

Class atg.commerce.profile.CommercePropertyManager is a subclass of
atg.userprofiling.PropertyManager. It provides additional access to profile property names specific to
Commerce customers that are used by CommerceProfileTools.

Example: The shipping address property names are stored in CommercePropertyManager. This provides
a convenient central location to store property names that may change depending on the site.

Create User Profile

The User Profile can be created by

1. Extending the Commerce profile Form Handler

2. Extending the repository userProfile.xml

3. Profile groups or segments to be used to target the specific customers.

Create Profile Group

ACC is used to create user groups such as Anonymous users, Members, Administrators etc. It can be
configured to allow anonymous users to visit the site, to browse the catalog and other pages, or they
can register as members through a registration page.

Returning registered members can log in with their user names and passwords. Once they log in,
members can access the My Profile page that allows them to maintain personal and commerce
profiles and to track their order information.

Administrators can view and manipulate user profile data using the Profile interface in the ACC.
This interface enables them to search, create, edit, duplicate, and delete user profiles.

Current Location Property

The user profile has a property called currentLocation (/atg/userprofiling/Profile.currentLocation) that
may be used by complex targeting systems to enable the targeter to know what kind of targeting
information is available.

That enable targeters to know what kind of targeting information is available.

It is an enumerated property type whose choices can be unknown, home, store_home,
shopping_cart, catalog_category, catalog_product, catalog_search, checkout, and profile.
In a category page, we can set the property like shown below.

ATG Page 57
 ATG Framework and Components

Catalog Management
Product Catalog
The Product Catalog is a primary component in the Commerce Application. It is a repository containing
repository items like category, products, media, etc. This provides an organizational framework to a
commerce site. ATG Commerce includes a default catalog which can be extended as per the need.
Catalog repository items can be edited using ATG Control Center (ACC).

In ATG Commerce, the product catalog is an ATG repository and the various elements of the catalog
(such as categories, products, and images) are repository items. The product catalog is built by adding
new repository items and defining relationships between them.

A product catalog is a hierarchical tree of categories and products.

Extending default Product Catalog

ATG Consumer Commerce comes with an XML definition file that contains the information for the
standard product catalog. A reference to this XML file is found in the
/atg/commerce/catalog/ProductCatalog component. The location of this XML file is
/atg/commerce/catalog/productCatalog.xml

Xml-combine is used to extend the default catalog. These extensions can be created to add properties
to categories, products and skus. But new tables must be created in the database to accommodate the
extended properties.

Xml combine tag is use to extend default catalog.

xml-combine="replace"

xml-combine="remove"

xml-combine="append"

xml-combine="append-without-matching"

xml-combine="prepend"

xml-combine="prepend-without-matching"

Category Product and SKU

The main item types for standard catalogs are categories, products and SKUs (Stock Keeping Units).

A product is a navigational end-point in the catalog. But, customers purchase a SKU and not a product.
A product may have several different SKUs associated with it, representing varieties, sizes, and colors.

ATG Page 58
 ATG Framework and Components

For example, a product that represents a specific shirt might have many associated SKUs, representing
different combinations of size and color

Catalog Navigation
A catalog home page displays a list of root categories. ATG provide targeters to find root categories.
Category is considered to be a root category if their root category property is set to true.

Developers can use TargetingForEach droplet which uses the RootCategories targeter to find root
categories.

Categories, products and skus can be displayed using CategoryLookup, ProductLookup and SKULookup
droplets respectively.

Navigation History and Breadcrumbs

ATG provides some components to keep a track of the path a customer follows when browsing a
website. Using these components, a list of the items the customer visited can be constructed and can be
displayed as links so that the customer can navigate back using them. These links are called
Breadcrumbs.

ATG Commerce provides CatalogNavHistory component to track the customers path through the
catalog. The component is placed under /atg/commerce/catalog/CatalogNavHistory. The component
uses the following input parameters.

1. navAction - operation to be performed on the stack. Options are push, pop and jump. A blank
navAction is treated as push.

2. navCount - to detect use of the Back button and should be passed in with any link that leads to
a page that uses breadcrumbs.

ATG Page 59
 ATG Framework and Components

Custom Catalogs
Custom catalogs are an important feature for commerce websites. It is needed to provide information to
particular customers or companies. The Product Catalog can be altered to create a number of sub-
catalogs representing the smallest section of the inventory that the customers want to view.

A custom catalog can be setup in following 3 steps.

Step 1: Create a new database to accommodate the custom catalog data.

Step 2: Configure the product catalog repository to use the custom catalog xml file. Define the path of
this repository in the productCatalog.properties file.

Step 3: To keep the atg.repository.servlet. ItemLookupDroplet from returning an item that is not in the
current catalog, change the following servlet beans.

/atg/commerce/catalog/CategoryLookup.properties

/atg/commerce/catalog/SkuLookup.properties

/atg/commerce/catalog/ProductLookup.properties

And use the following class:

$class=atg.commerce.catalog.custom.CatalogItemLookupDroplet

ATG Page 60
 ATG Framework and Components

Order Management
ATG Order management supports functionality like

Adding, editing, deleting items to a shopping cart,

Calculating the promotions if exists

Ensuring items are shipped by the preferred method

Validating credit card information.

Multiple shopping carts for user

Multiple shipping and payment methods

Provides various types of checkout like ExpressCheckout/Expedited Checkout, normal checkout,

complex checkout etc

Payment Integration with Cybersource, Cybercash

Order History

ATG Order Components (OTB)

ATG provide good number of out of box components for Order Management feature. Few of them are
listed below.

Shopping cart
Shopping Cart is an Order in incomplete state.

Order
Orders are in process. Customers can have an unlimited number of orders in existence at one time.

Order Holder
This class maintains the current Order object as well as a collection of saved Order objects. The
component that utilizes OrderHolder is /atg/commerce/ShoppingCart, a session-scoped component
whose handleXXX methods add, delete, and switch between carts

Order Repository
Repository to store the Order details

Order Manager
There is a business layer class called as OrderManager which takes care of
creating/loading/refreshing/updating the orders. This component in turn interacts with the Pipeline
processors. Order Manager interacts with the pipeline processors.

ATG Page 61
 ATG Framework and Components

Pipeline
Includes a sequence of Pipeline processors to do the job in a fine grained transactionally aware manner
for order submission and payment. This pipeline contains the sequence of processors for order
submission and payment.

Payment Manager
There is a component called as PaymentManager which in turns interfaces with Payment Pipeline to talk
to the third-party payment gateways to ensure that the CreditCard authorization/debit is handled
seamlessly.

Form Handlers
CartModifierFormHandler, ShoppingCartModifier, ExpressCheckoutFormHandler etc. are used to
manage the Shopping Carts

Droplets
RepriceOrderDroplet, PriceEachItem, PriceItem etc. which are used to display the price of the SKUs.

ShippingGroupsDroplet, PaymentGroupsDroplet which can help in accumulating necessary information.

OrderTools
OrderTools contains a set of properties that you can use to customize the purchase process. The default
property settings should be suitable for most sites, but can be changed.

ATG Order Java Interfaces

Order
The Order interface represents the delivery and payment information for a collection of items. An Order
contains CommerceItems, ShippingGroups, PaymentGroups, and Relationships.

CommerceItem
The CommerceItem interface represents information about a product to be purchased. A
CommerceItem contains the SKU (also called the catalogRefId) and the quantity of the item purchased.

ShippingGroup
The ShippingGroup interface contains information about the delivery of a collection of CommerceItem
objects. A ShippingGroup could contain a physical delivery address.

PaymentGroup
The PaymentGroup interface contains payment information, shipping costs, and tax information for
each item or the entire Order. This includes information such as a credit card number, an expiration
date, and the amount to be charged.

ATG Page 62
 ATG Framework and Components

Relationship
The Relationship interface represents an association between two or more of the commerce objects
listed above, such as the relationship between a CommerceItem and a ShippingGroup.

HandlingInstruction
The HandlingInstruction interface describes special handling for a CommerceItem within a given
ShippingGroup. Gift wrapping is an example of HandlingInstruction.

ATG Order Java Classes

Order Classes
OrderImpl: This class implements Order. It contains data structures for managing collections of
other commerce objects. It manages collections of CommerceItem, ShippingGroup,
PaymentGroup, and Relationship objects.

Item Classes
CommerceItemImpl: This class implements CommerceItem. It stores the data about a specific
item in an Order.

Shipping classes
ShippingGroupImpl -This class implements ShippingGroup. It stores the data describing where
and how to ship CommerceItems, as well as the Relationships to items in the shipping group.
This class provides no functionality itself.

There are 2 subclasses which have actual implementation called HardgoodShippingGroup and
ElectronicShippingGroup.

HardgoodShippingGroup - This class implements ShippingGroup and extends

ShippingGroupImpl. In addition to storing inherited data, it stores information about how the
CommerceItems are to be shipped to a physical street address, such as the carrier and
postaladdress.

ElectronicShippingGroup - This class implements ShippingGroup and extends

ShippingGroupImpl. In addition to storing inherited data, it stores information about how
CommerceItems are to be delivered electronically, such as an e-mail address.

Payment Classes
PaymentGroupImpl - This class implements PaymentGroup. It stores the payment information
for CommerceItems, shipping costs, and tax. It also can contain Relationships to those items,
shipping costs, or tax costs in the PaymentGroup.

ATG Page 63
 ATG Framework and Components

This class provides no functionality itself, but is used through the CreditCard and GiftCertificate
subclasses.

CreditCard - This class implements PaymentGroup and extends PaymentGroupImpl. In addition

to storing inherited data, it stores information about how CommerceItems, shipping costs, and
tax costs are paid for using a credit card.

GiftCertificate - This class implements PaymentGroup and extends PaymentGroupImpl. In

addition to storing inherited data, it stores information about how CommerceItems, shipping
costs, and tax costs are paid for using a gift certificate.

StoreCredit - This class implements PaymentGroup and extends PaymentGroupImpl. In addition

to storing inherited data, it stores information about how CommerceItems, shipping costs, and
tax costs are paid for using a store credit.

Relationship classes
ShippingGroupCommerceItemRelationship - When this Relationship is added to a
ShippingGroup and CommerceItem, the CommerceItem is shipped using the information in the
ShippingGroup. This Relationship object itself contains data such as the quantity to be shipped.

PaymentGroupCommerceItemRelationship - When this Relationship is added to a

PaymentGroup and CommerceItem, the CommerceItem is paid for using the information in the
PaymentGroup. This Relationship object itself contains data such as the quantity of the item to
be paid for using the PaymentGroup.

PaymentGroupShippingGroupRelationship - When this Relationship is added to a

PaymentGroup and ShippingGroup, the shipping cost is paid for using the information in the
PaymentGroup. This Relationship object itself contains data such as the amount of the shipping
cost to be paid for using the PaymentGroup.pShippingGroupRelationship.

PaymentGroupOrderRelationship - When this Relationship is added to a PaymentGroup and

Order, the tax cost or order cost is paid for using the information in the PaymentGroup. This
Relationship object itself contains data such as the amount of the tax cost to be paid for using
the PaymentGroup.

Handling Classes
HandlingInstructionImpl - This class implements HandlingInstruction. It contains a
ShippingGroup ID, CommerceItem ID, and quantity, as well as data about what quantity of
CommerceItems in which ShippingGroups need special handling. This class provides no
functionality itself, but should be used through a subclass like GiftlistHandlingInstruction.

GiftlistHandlingInstruction - This class implements HandlingInstruction and extends

HandlingInstructionImpl. In addition to storing all the basic data that it inherits, it also stores
data about which CommerceItems in the Order were added from a gift list.

ATG Page 64
 ATG Framework and Components

Address classes
There are two classes atg.core.util.Address and atg.core.util.ContactInfo. These objects are referenced
when a user checks out. We need to extend these objects to track additional information about your
users if needed.

atg.core.util.Address

atg.core.util.ContactInfo

These classes address Properties like firstName, middleName, lastName, address1, address2, City,
state,country, postalCode, ownerId and ContactInfo Properties like phoneNumber, faxNumber, email.

Business Layer Classes

The business layer classes contain the logic and business rules for the purchase process. The methods
within these classes are used to make changes to an Order. These methods contain the logic that alters
the Orders data structure and maintains its accuracy. Following are business layer classes

OrderTools

OrderManager

CommerceItemManager

ShippingGroupManager

HandlingInstructionManager

PaymentGroupManager

OrderQueries

SimpleOrderManager

Customizing OrderTools
OrderTools need to be customized when the order module is extended. The OrderTools component is
located in Nucleus at /atg/commerce/order/.

The following OrderTool properties can be customized.

orderTypeClassMap, defaultOrderType, commerceItemTypeClassMap, defaultCommerceItemType,

shippingTypeClassMap, defaultShippingGroupType, defaultShippingGroupAddressType,
paymentTypeClassMap, defaultPaymentGroupType, defaultPaymentGroupAddressType,
relationshipTypeClassMap, beanNameToItemDescriptorMap,

ATG Page 65
 ATG Framework and Components

orderTypeClassMap
This property defines the type-to-class name mapping for Order objects. You can have more than one
type of Order object. When creating a new Order, a string is passed as a parameter to the create
method. (For example, the string default could be passed.) This constructs an instance of an Order
class that is mapped to that string.

commerceItemTypeClassMap
This property defines the type-to-class name mapping for CommerceItem objects. You can have more
than one type of CommerceItem object. When creating a new CommerceItem, a string is passed as a
parameter to the create method. (For example, the string default could be passed.) This constructs an
instance of a CommerceItem class that is mapped to that string.

shippingTypeClassMap
This property defines the type-to-class name mapping for ShippingGroup objects. You can have more
than one type of ShippingGroup object. When creating a new ShippingGroup, a string is passed as a
parameter to the create method. (For example, the string hardgoodShippingGroup could be passed.)
This constructs an instance of a ShippingGroup class that is mapped to that string.

paymentTypeClassMap
This property defines the type-to-class name mapping for PaymentGroup objects. You can have more
than one type of PaymentGroup object. When creating a new PaymentGroup, a string is passed as a
parameter to the create method. (For example, the string creditCard could be passed.) This constructs
an instance of a PaymentGroup class that is mapped to that string.

ATG Page 66
 ATG Framework and Components

relationshipTypeClassMap
This property defines the type-to-class name mapping for Relationship objects. You can have more than
one type of Relationship object. Relationships are not created directly by a user. Relationships are
created by methods based on the type of relationship that the method needs.

The relationshipTypeClassMap property maps a name to a class. It is used to configure the class type
that will be instantiated when a request to construct a relationship is made. By overriding the default
values, you can customize the environment to use a Relationship class you have subclassed.

beanNameToItemDescriptorMap
This property maps a bean name to an OrderRepository item descriptor name. When saving an Order,
the processors that contain the code for saving look for an OrderRepository item descriptor with the
same name as the bean class. The beanNameToItemDescriptorMap property contains this mapping.

All objects that can be mapped to an item descriptor are listed in the beanNameToItemDescriptorMap.
The format is <bean name>=<repository item descriptor>. The example below demonstrates how a
mapping is defined in the properties file. The following code defines the default values.

ATG Page 67
 ATG Framework and Components

defaultOrderType
This property defines the default Order type. In the example below, the default type is defined as the
string default, which in turn maps to a class in the orderTypeClassMap property. The following code
defines the default value.

defaultCommerceItemType
This property defines the default CommerceItem type. In the example below, the default type is defined
as the string default, which in turn maps to a class in the commerceItemTypeClassMap property. The
following code defines the default value.

defaultShippingGroupType
This property defines the default ShippingGroup type. In the example below, the default type is defined
as the string hardgoodShippingGroup, which in turn maps to a class in the shippingTypeClassMap
property. The following code defines the default value.

defaultShippingGroupAddressType
This property defines the default ShippingGroupAddressType. To customize your address information
you need to subclass RepositoryContactInfo and use your new class name for the
defaultShippingGroupAddressType.

defaultPaymentGroupType
This property defines the default PaymentGroup type. In the example below, the default type is defined
as the string creditCard , which in turn maps to a class in the paymentTypeClassMap property. The
following code defines the default value.

defaultPaymentGroupAddressType
This property defines the default PaymentGroupAddressType. To customize your address information
you need to subclass RepositoryContactInfo and use your new class name for the
defaultPaymentGroupAddressType.

ATG Page 68
 ATG Framework and Components

Order Repository
The Order Repository is the layer between ATG Commerce and the database server. The repository is
where Orders are saved after processing and stored in between customers visits to your site. It is
implemented using a SQL repository.

The beanNameToItemDescriptorMap property of the OrderTools component maps the Order Repository
item descriptors to Bean names. In ATG Commerce, the processors that save and load an Order look for
an item descriptor that is mapped to the corresponding commerce object class; the
beanNameToItemDescriptorMap property contains this mapping.

The base Order Repository definition file is located at

<ATG9.0dir>/DCS/config/atg/commerce/order/orderrepository.xml.

In ATG Consumer Commerce, this base file is combined with an additional definition file that is located
at <ATG9.0dir>/B2CCommerce/config/atg/commerce/order/orderrepository.xml.

In ATG Business Commerce, this base file is combined with an additional definition file that is located
at<ATG9.0dir>/B2BCommerce/config/atg/commerce/order/orderrepository.xml

ATG Page 69
 ATG Framework and Components

Pre-checkout Process
Shopping cart Creation
The shopping cart can be implemented by following steps.

1. Shopping cart can be implemented using cartModifierFormhandler or extending

cartModifierFormHandler. This java class has package
/atg/commerce/order/purchase/CartModifierFormhandler.

2. ProductLookupDroplet and SkuLookupDroplet to retreive product and sku by passing productid

and skuId.

3. CartModifierFormhandler contains many handle methods to add product to shopping cart.

Repository id of product and sku needs to be passed to cartModifierFormhandler to add the
same to cart.

4. Above repository Ids are passed as hidden parameters in form. These Ids goes to
cartModifierFormhandler when user submits form by clicking add to cart button.

5. These values are passed to the as hidden fields when the user pushes the Add To Cart submit
button provided by us.

6. When add to cart button is clicked then handleAddItemToOrder method is invoked in

CartModifierFormHandler. This method adds item to order.

7. handleAddItemToOrder method of CartModiferFormhandler internally calls api of

PurchaseProcessFormhandler and PurchaseProcessHelper to add items to order.

8. Finally handleAddItemToOrder method of CartModifierFormhandler call updateOrder() method

of OrderManager Class to save order to repository.

PurchaseProcessFormHandler
This abstract class defines the very general FormHandling functionality that the purchase process
formhandlers require, including Transaction management, PipelineChain execution, central
configuration, and error processing.

PurchaseProcessHelper
PurchaseProcessHelper contains the common functionality required by the purchase process form
handlers as well as commerce web services.

ATG Page 70
 ATG Framework and Components

Order Creation
There are many api exposed by OrderManager to create an order. The type of order created depends on
an api used to create an order. OrderManager internally uses OrderTool api to create order. The
orderType parameter decides the type of order to be created. If orderType parameter is null then
defaultOrderType is created using OrderTool. We need to pass profileId to createOrder() method for
creating the order.

Multiple orders creation for an user

Creating multiple orders requires atg.commerce.order.OrderHolder in addition to
atg.commerce.order.Order. Customers can have an unlimited number of orders in existence at one
time.

OrderHolder class maintains the current Order object as well as a collection of saved Order objects. The
component that utilizes OrderHolder is /atg/commerce/ShoppingCart, a session-scoped component
whose handleXXX methods add, delete, and switch between carts.

Multiple shopping carts can be implemented by using the handleCreate method of the OrderHolder
class. This method creates a new Order and sets it as the currentOrder in the OrderHolder. Any
previously existing Order object is placed into the collection of saved carts.

Saving Modifying Repricing Orders

In order to save, modify or repricing the order we need an instance of CartModifierFormHandler class.
This is located in Nucleus at /atg/commerce/order/purchase/CartModifierFormHandler.

Saving Order
Many of the methods in CartModifierFormHandler call OrderManager.updateOrder() to save the Order
in its present state to the Order Repository.

Modify Order
It provides methods to modify an Order by catalogRefId of CommerceItem.

handleSetOrder()

handleRemoveItemFromOrder()

handleMoveToPurchaseInfo() This method checks for any modification in the order then it
starts the checkout process.

ATG Page 71
 ATG Framework and Components

RepriceOrder
The handleAddXXX and handleRemoveXXX methods of CartModifierFormHandler automatically reprice
the Order whenever the user makes changes to it. These handle methods internally calls
createRepriceParameterMap() method of PurchaseProcessFormhandler to reprice an order.

However, if the users make changes to their orders through other purchase process form handlers that
do not reprice orders, such as the form handlers that create and manage shipping groups, then
RepriceOrderDroplet servlet bean is used to reprice the Order before displaying its price to the user.

Extending Purchase Process

Creates a new class called MyCommerceItemImpl by extending CommerceItemImpl and adds a new
String properties e.g. shortDescriptioon.

The calls to getPropertyValue() and setPropertyValue() retrieve and set the values of properties directly
on the repository item objects; they are part of the atg.commerce.order.ChangedProperties interface.

ChangedProperties Java Interface

The ChangedProperties interface enhances performance when saving an Order to the Order Repository.
In ATG Commerce, all commerce objects implements ChangedProperties interface except for
atg.commerce.order.AuxiliaryData and all subclasses of atg.commerce.pricing.AmountInfo.

The commerce object that supports the ChangedProperties interface, every get() method needs to call
the getPropertyValue() method, and similarly every set() method needs to call the setPropertyValue()
method.

This reduces the amount of processing when the OrderManager.updateOrder() is called to save order to
repository. This enhances the performance because we set the value directly to repository item and
saving the only property that is actually changed. Call to getPropertyValue("PropertyName") retreive the
property directly from repository item and eliminate the need to create member variable in the class
that are not changed.

ATG Page 72
 ATG Framework and Components

In the example above, the call to setPropertyValue("shortDescription", pShortDescription) in the

setShortDescription() method causes the shortDescription repository item property to be set directly
when the method is called.

Advantages
Reduces the amount of processing when OrderManager.updateOrder() is called to save the
Order to the repository.

Enhances the performance because we set the values directly to the repository item and save
the properties only that have actually been changed in the class. The call to
getPropertyValue("shortDescription") retrieves the property directly from the repository item
and eliminates the need to create a member variable in the class to store the value.

ATG Page 73
 ATG Framework and Components

Checkout Process
Checkout process is initiated when the order is submitted. ATG supports following 3 types of checkout.

1. Express Checkout / Expedited Checkout

2. Complex checkout

3. Simple checkout

ExpressCheckout/Expedited Checkout
Express checkout supports the use of only a single profile HardgoodShippingGroup and a single profile
CreditCard for a given Order. It retrieves the predefined shipping group and payment group at runtime
automatically from user profile. We can manage and expedite the pre-checkout process for Orders using
the ExpressCheckoutFormHandler.

It supports the following methods

handleExpressCheckout - invokes the runRepricingProcess() method to reprice the Order, then

calls OrderManager.updateOrder() to save the Order in its present state to the Order
Repository, and finally calls commitOrder() to submit the Order for checkout.

runRepricingProcess - Reprices the Order by running the pipeline specified in

ExpressCheckoutFormHandler.repriceOrderChainId. Bydefault, this property is set to
repriceOrder.

commitOrder - used to submit the current Order for checkout. The method then calls the
OrderManager.processOrder() method, which executes the processOrder pipeline.

Complex checkout
Provides several form handlers to support a checkout process that uses any number or type of shipping
group and payment group. Also Separate form handlers exist to support the following tasks:

CreateShippingGroupFormHandler - Creating shipping groups.

ShippingGroupFormHandler - Associating shipping groups with an Order and its items.

CreatePaymentGroupFormHandler - Creating payment groups.

PaymentGroupFormHandler - Associating payment groups with an Order and its items.

CommitOrderFormHandler - Submitting an Order for checkout .

Simple Checkout
It is same as Express checkout but expects the user to fill in the shipping and payment group during
checkout.

ATG Page 74
 ATG Framework and Components

Order Pipeline
Order pipeline is used to process order. Order processing occurs when a customer has supplied all the
necessary information for the Order and has submitted it for checkout.

1. The processing of an Order begins with a call from FormHandlers (CartModifierFormHandler) to

OrderManager.processOrder().

2. OrderManager.processOrder calls the PipelineManager to execute the processOrder pipeline

which is configured in Commerce Pipeline.xml located at
/<ATG9.0dir>/B2CCommerce/config/atg/commerce/commercepipeline.xml

3. The processOrder pipeline first validates an order by calling executeValidateForCheckoutChain

processor in the pipeline. This is a first processor in processorder pipeline and then invokes the
sequence of processor in the pipeline. Call to executeValidateForCheckoutChain processor
internally calls validateForCheckout pipeline.

4. Each processor after execution returns a status code and determines which processor in the
chain to execute next.

5. The Pipeline Manager enables us to dynamically add and remove processors and chains of
processors.

ATG Page 75
 ATG Framework and Components

Running a processor chain

PipelineManager is responsible to call any processor chain using runProcess method. Pipeline manager
start the processor chain by invoking the runProcess() method of first processor in the chain and passes
it the user data.

The runProcess() method is called on the head PipelineLink object of the processor chain and it is
responsible for following tasks.

1. handling the transaction (if required)

2. executing the processor, and

3. Returning the return code to the PipelineChain. If status code is 0 then it tell PipelineManager to
stop this chain or if the code is other then 0 then it calls the next processor to execute.

Four methods are called before and after the call to runProcess() in the PipelineProcessor to handle the
transaction in the following order

preChainTransaction()

postChainTransaction()

preLinkTransaction()

postLinkTransaction()

The runProcess() method is called between these methods and the call is returned to the PipelineChain
with a return value. If the return value is 0 (PipelineProcessor.STOP_CHAIN_EXECUTION), it tells the
PipelineManager that execution for this chain should be stopped. If the return value is other than o,
then it calls the next processor to execute.

User defined Processor Pipeline

Pipelines can be created/deleted in following two ways.

XML file
Pipeline Manager can be initialized with a set of processor chains at startup using an XML configuration
file called a pipeline definition file. It is a simple way to construct and manage the global
PipelineManager without writing code. CommercePipeline.xml is the sample pipeline definition file
provided.

A processor in a pipeline can be extended by overriding runProcess() method, and can be configured in
the pipeline. ACCs PipelineEditor is used for creating, deleting or modifying the Pipelines graphically.

atg.service.pipeline API
Any non-globally scoped Pipeline Managers need to be created using the API.

ATG Page 76
 ATG Framework and Components

Tags in Pipeline Definition File

PipelineManager
The top level tag that encloses a definition of a Pipeline Manager.

PipelineChain
Tag defining a given processor chain in the Pipeline Manager.

name - (required) the name of the processor chain

headlink - (required) the first processor in the chain to be executed

transaction - the default transactional mode of all the processors in this chain

classname - the full name of a Java class which is to be instantiated and used as the
PipelineChain object. The default is atg.service.pipeline.PipelineChain. The value must be this
class or a subclass of it.

resultclassname - the full name of a Java class which is to be instantiated and used as the
PipelineResult object

Pipelinelink
Defines a processor within the chain and names it.

Processor
The name of the Pipeline Processor object.

Transition
A reference to the next link to be executed mapped by a return value.

Transaction Handling
The valid transaction modes are as follow.

TX_REQUIRED

TX_REQUIRES_NEW

TX_SUPPORTS

TX_NOT_SUPPORTED

TX_MANDATORY

ATG Page 77
 ATG Framework and Components

Payment Process
The Payment Process is handled by payment pipelines and payment pipeline is called by
PaymentManager. It manages the authorization, debit, and credit of PaymentGroups in an Order, and it
tracks the results of those payment operations using PaymentStatus objects.

A seperate payment pipeline is defined for each type of payment group i.e. creditcard, giftcertificate and
storecredit. PaymentManager consist of methods like authorize(), credit() and debit(). These methods
take the order object and one paymentgroup or list of paymentgroup as parameters. It performs
payment operation by calling appropriate payment pipeline according to paymentgroup passed as
parameter.

creditCardProcessorChain - pipeline handles authorization, debit, and credit work for the
atg.commerce.order.CreditCard

giftCertificateProcessorChain - pipeline handles authorization, debit, and credit work for the
atg.commerce.order.GiftCertificate class.

They are configured in paymentGroupToChainNameMap of PaymentManager.

Payment Pipeline chain

Each of the payment pipelines is composed of two processors.

1. First processor - Aggregates the information required to performing the requested payment
action and creates an XXXInfo object for use in that action.

Example for CreditcardProcessorChain, the action is CREDIT and the CreditCardInfo is the action
object.

2. Second processor - Performs the actual operation authorizing, debiting, or crediting the
appropriate payment method.

ATG Page 78
 ATG Framework and Components

Note:
By default a single pipeline exists to perform authorize, debit, and credit actions for a single
PaymentGroup type. ATG supports to split them into separate pipelines if it needs to be handled
differently.

Order Fulfillment
ATG Commerce provides extension points to link the Commerce system with any Fulfillment system.
One of the processor in the commerce pipeline called as sendOrderFulfillmentMessage can be
configured to send out a JMS message to the designated fulfillment system. ATG commerce comes with
a simple implementation of a Fulfillment system that can be accessed via the Dynamo Admin UI.

ATG Page 79
 ATG Framework and Components

Pricing and Promotions

PricingModel
Pricing model is a repository item that describes a discount. It includes a PMDL rule and the discount
type and amount. It also contains information about when the pricing model may be used. ACC is used
to set up the prices and promotions for the products in the catalog.

Every product can have two pricing models.

Standard Prices
Standard prices are the prices specified for the product in the catalog. The prices specified with the
catalog are list price and sales price. The list price is the full, undiscounted price of a product. The sales
price represents actual selling price for an item on sale.

The boolean property On Sale indicates whether the item is on sale or not. The system uses this flag to
determine the base price of the item.

Promotional prices
Promotional price is the price after applying the promotions or discounts. Different prices can be offered
depending on circumstances such as timing, other products being purchased, or the customer's profile
by calculating dynamically using a combination of standard prices and promotions.

PMDL (Pricing Model Definition Language)

PMDL is used to describe promotions. This includes the discount rules for when a promotion may apply
and the rules for what may be discounted. These two pieces are called the qualifier (when) and the
target (what) and are a part of every promotion. The ACC and BCC include a discount rule interface for
creating rules.

Droplet for displaying price

PriceItemDroplet
Component used is /atg/commerce/pricing/PriceItem

Use to display the amount price that is calculated dynamically by the pricing engine for a
particular user at a particular time. It calculates different prices for the same item depending on
whether that item is displayed alone (for example, in the product template page of the catalog)
or in the context of the shopping cart of an item dynamically.

PriceItem takes a SKU repository item as its item parameter. It outputs an element parameter
that is of type CommerceItemImpl that is renamed to SKU using the elementName parameter

RepriceOrderDroplet
Component used is /atg/commerce/order/purchase/RepriceOrderDroplet

ATG Page 80
 ATG Framework and Components

It is use to reprice an order by sending a required parameter which specified pricing operation
to execute. Pricing operations are defined in the atg.commerce.pricing.PricingConstants
interface.

They are ORDER_TOTAL, ORDER_SUBTOTAL, ORDER_SUBTOTAL_SHIPPING,

ORDER_SUBTOTAL_TAX, ITEMS, SHIPPING, ORDER, TAX, NO_REPRICE

ATG Pricing Services

The pricing services provide a flexible system for personalizing the prices of items in product catalog.
The content for every shopper can be personalized to show different categories and the prices can be
tailored dynamically. Thus the system is granular enough to create a system with the facility of pricing
the items differently for different shoppers.

Pricing services comprises of following two components. These components work together to determine
prices for catalog items, total orders, sales tax, and shipping.

1. Pricing Engines

2. Pricing Calculators

Pricing Engine
Pricing engine is mainly responsible for following three tasks.

1. Retrieving any promotions that are available to the site visitor.

2. Determining which calculators generate the price.

3. Invoking the calculators in the correct order.

Pricing calculators
Pricing calculators are responsible for the following tasks.

1. Looking up the price in the catalog by priceList.

2. Invoking a qualifier service that identifies the objects to discount.

3. Determine price using the information received from the engines and from the qualifier.

Pricing Objects

Items
List Price property of the product catalog is used to specify the list price of an item. Pricing services uses
the list price to calculate the new price based on the promotions or discounts applied on it.

ATG Page 81
 ATG Framework and Components

Order
It calculates the total cost of an order and apply any discount that is applicable (for example, a customer
might have a coupon offering a 10% discount on a total order).

Shipping price
It calculates the price of shipping for an order and apply discounts if applicable.

Tax
It calculates the sales tax for an order. Alternatively, sites can use a third-party system such as
CyberSource or TAXWARE to handle tax calculations.

Price Calculation Flow

1. During checkout, PriceItem servlet bean in a page or from the ATG Commerce PricingTools class
calls the pricing engine.

2. The pricing engine applies its configured precalculators. A precalculator modifies a price without
using any associated promotions.

For example, a site could use a list price precalculator or an order subtotal precalculator to
establish a base price to which subsequent calculators will apply a discount.

All the precalculators (defined in ItemPricingEngine) are executed in order. This includes the
following.

listPrice (fixed price, bulk price, tiered price)

salePrice (if item is on sale)

3. The pricing engine accesses the current customers profile and retrieves any promotions listed in
the activePromotions property of the profile.

4. The pricing engine builds a list of global promotions. It builds the list by using its
globalPromotionsQuery property to query the Promotions repository, searching for any
promotion given to all customers (global).

5. The resulting lists are concatenated. The pricing engine processes one at a time. It applies
promotions by priority.

6. The pricing engine applies its configured PostCalculators, which make any necessary
modifications to the price after any discounts have been applied.

ATG Page 82
 ATG Framework and Components

Pricing Calculators

Shipping calculators
All the shipping Calculators in our application are configured as preCalculators for ShippingPricingEngine
at /atg/commerce/pricing/ShippingPricingEngine.properties (corresponding java class
com.ebg.sec.order.pricing.SECShippingPriceEngineImpl).

Tax calculators
Similarly, all the Tax calculators are configured as preCalculators for TaxPricingEngine at
/atg/commerce/pricing/TaxPricingEngine.properties (corresponding java class
com.ebg.sec.order.pricing.SECTaxPriceEngineImpl).

Shipping and Tax Pricing Engines calculate the shipping cost and tax (as applicable) using configured
Shipping and Tax Calculators, respectively. getPreCalculators() method of
com.ebg.sec.order.pricing.SECShippingPriceEngineImpl returns an array of configured shipping
calculators , while getPreCalculators() method of com.ebg.sec.order.pricing.SECTaxPriceEngineImpl
returns an array of configured tax calculators.

Pricing Engine implementation

SECShippingPriceEngineImpl
SECShippingPriceEngineImpl extends atg.commerce.pricing.ShippingPricingEngineImpl, the component
for SECShippingPriceEngineImpl is available at /atg/commerce/pricing/ShippingPricingEngine. Following
calculators are configured as its pre Calculators.

SECShippingCalculatorImpl_en_US
The component for this calculator is available at
/atg/commerce/pricing/SECShippingCalculatorImpl_en_US. Following method calculate the
shipping cost for particular order.

SECShippingDiscountCalculator_en_US
The component for this calculator is available at
/atg/commerce/pricing/SECShippingDiscountCalculator_en_US. Following method of this
calculator calculates the discounted shipping cost for particular order.

ATG Page 83
 ATG Framework and Components

SECTaxPriceEngineImpl
SECTaxPriceEngineImpl extends atg.commerce.pricing.TaxPricingEngineImpl , the component for
SECTaxPriceEngineImpl is available at /atg/commerce/pricing/TaxPricingEngine. Following calculators
are configured as its pre Calculators.

SECTaxProcessorTaxCalculator_en_US
The component for this calculator is available at
/atg/commerce/pricing/SECTaxProcessorTaxCalculator_en_US. Following method of this calculator
calculates the applicable tax.

SECTaxDiscountCalculator_en_US
The component for this calculator is available at
/atg/commerce/pricing/SECTaxDiscountCalculator_en_US. Following method of this calculator
calculates the applicable tax.

ATG Page 84
 ATG Framework and Components

Promotions
ATG supports dynamic set up of offers or promotions on specific products or groups of products. Users
can set up promotions from ACC. Promotions are stored in the Promotions repository, which is one of
the default ATG Commerce repositories.

Promotions can be any kind such as fixed price off, percentage off or in terms of another free product,
free shipping etc. The system also treats coupons as a type of promotion. Examples of promotions are.

1. Specific amount off a particular product

2. Specific amount off a whole order

3. Percentage amount off a particular product

4. Percentage amount off a whole order

5. Specific amount or percentage off a product based on an attribute

6. Free product or free order

7. Free shipping for a specific product

Promotions can be applied at 4 levels based on the priority set. By default, the following is the priority
level to apply promotions.

Item level

Order level

Shipping level

Tax level.

ATG scenarios support the set up of cross sell and up sell features.

Attributes to manage promotions

Following are the three important attributes to manage promotion for each user.

activePromotions
Stores the list of promotions that can be used by the user in pricing their orders.

usedPromotions
Stores any promotions used in an order.

inactivePromotions
Stores promotions that can no longer be used. A promotion would be moved into the inactive list.

ATG Page 85
 ATG Framework and Components

eCoupon
Coupons are a type of promotion (20% of an order over $100, for example) sent to specific customers.
Customers redeem coupons by entering a claim code during the checkout process. You can use the ATG
Control Center or BCC to manage coupon repository items.

Creating an eCoupon is a two step process.

1. Create a promotion.

2. Create a coupon and associate it with promotion created in step 1.

Coupon FormHandler

SECCouponFormHandler
Class com.ebg.sec.order.formhandler.SECCouponFormHandler extends
atg.commerce.promotion.CouponFormHandler. SECCouponFormHandler is the java class created to
handle coupon addition and removal from an order.

Methods used in SECCouponFormHandler are as follow.

handleClaimCoupon() - To claim a coupon code and add it to order.

handleRemoveCoupon() - To remove an already applied coupon from the order.

Gift certificate
Gift certificate represents another mode of payment, just like credit card payment. Gift certificates allow
a customer to pay for all or part of a purchase using a prepaid amount. By providing gift certificates as
an option for your customers, you can increase sales and attract new business.

Processing a gift certificate involves the following steps.

1. Customer A purchases the gift certificate on behalf of Customer B.

2. ATG Commerce fulfills the purchase for Customer A (and sends a notification e-mail to
Customer B as part of the fulfillment process).

3. Customer B uses (claims) the gift certificate to pay for all or part of an order.

Gift certificate FormHandler

SECPurchaseProcessFormHandler
Class com.ebg.sec.order.formhandler.SECPurchaseProcessFormHandler is the java class created to
handle gift certificate addition to an order.

Methods used in SECPurchaseProcessFormHandler are as follow.

ATG Page 86
 ATG Framework and Components

handleClaimGiftCertificate() - To claim a gift certificate.

ATG Page 87
 ATG Framework and Components

Extra Info
/atg/userprofiling/B2CProfileFormHandler
Component is use to handle user specific operations like login, registration logoff etc.
It is extended from atg.commerce.profile. CommerceProfileFormHandler class.
It contains a Map property by name editValue that holds extra properties like Shipping
Address etc.
It also contains handler methods to check up credit cards for their format and there is a
converter to print the Credit card number masked.

/atg/commerce/catalog/CatalogNavHistory
Component to track the customers path through the catalog.
This component takes the following input parameters.
o navAction defines the operation type to be performed on stack. Options are push,
pop & jump. A blank navAction is treated as push.
o navCount

/atg/commerce/ShoppingCart
Shopping cart component is a session-scoped component whose handleXXX methods add,
delete, and switch between carts.
This component utilizes an object of OrderHolder class which contains the current order as well
as saved order objects.

OrderManager
Order manager is a business layer component which takes care of creating, loading, refreshing,
updating the orders.
This component also interacts with the pipeline processors.

Order Repository
Order repository stores an order details.

ATG Page 88
 ATG Framework and Components

Profile Repository

Dynamo SQL Profile Repository

It is pre-configured default repository for DPS. Using this, we can store, modify and query user profile
data in a SQL database.

Dynamo LDAP Profile Repository

Using this, we can store, modify and query user profile data in LDAP (Lightweight Directory Access
Protocol) directory.

Product Catalog
The Product Catalog is a primary component in the Commerce Application.
It is a repository containing repository items like category, products, media, images etc.
ATG Commerce application comes with a default product catalog which can be extended as per
business need.
Catalog repository items can be edited using ATG Control Center (ACC).
A product catalog is a hierarchical tree of categories and products.
Default product catalog xml file is /atg/commerce/catalog/ProductCatalog.
Default product catalogs can be extended to meet business needs.
o Xml-combine tag is used to extend the default catalog.
o Extensions can be created to add properties to categories, products and skus.
o New tables must be created in the database to accommodate the extended properties.
The main item types for the catalogs are categories, products and SKUs (Stock Keeping Units).
A product is a navigational end-point in the catalog. However, customers purchase a SKU and
not a product.
A product may have several different SKUs associated with it, representing varieties, sizes, and
colors.

Custom Catalog
Custom catalog is repository needed to provide information to particular customers or companies.

sortProperties
the sortProperties property of this component holds the property whose values determine the sort
order. By default, items are sorted by display name in alphabetical order.

A string that specifies how to sort the list of repository items. This parameter is specified as a comma
separated list of property names. The first name specifies the primary sort, the second specifies the
secondary sort, etc. If the first character of each keyword is a -, this sort is performed in descending
order. If it is a + or it is not a -, it is sorted in ascending order.

ATG Page 89
 ATG Framework and Components

Note: This parameter is only valid for repository items, it will not work with enumerated data-types.

ATG Page 90
 ATG Framework and Components

ATG Search Engine Optimization (SEO) Techniques

Search Engine Optimization technique is used to optimize the site for indexing purpose and to improve
the ranking of the page in search engine index. Here, Search Engine is referred to the engines used for
indexing the websites like Google, yahoo, Bing etc.

ATG out of box supports following SEO techniques to improve the ranking of our site.

Url Optimization

Meta Tag Implementation for JSP.

Canonical URLs for Products and Categories.

Sitemap Creation & Maintenance

We will discuss them in coming sections.

Disclaimer
SEO is vast topic and is not restricted to the techniques discussed here. This section is demonstrating the
SEO capabilities that ATG has implemented and supported.

ATG Page 91
 ATG Framework and Components

Repository
ATG SEO makes use of two repositories i.e. SEORepository & SitemapRepository to store SEO
information. Kindly refer Repository section to know basic about repositories.

SEORepository
All SEO related data is stored & maintain in SEO repository. This repository is extensible and can be
customized according to your project needs. The path of this repository is /atg/seo/SEORepository.

SitemapRepository
All sitemaps related information is stored in SitemapRepository. The path of this repository is
/atg/sitemap/SitemapRepository

ATG Page 92
 ATG Framework and Components

SEO Components
ATG has defined several components to fetch information from SEO and Sitemap repositories and
render SEO friendly pages for search engine robots. Following is the list of important components used
for SEO. Kindly refer Droplet section to know basic about droplets.

S.No Droplet Name Component Path Description

1 CatalogItemLink /atg/repository/seo/CatalogIte This Droplet is used to render page

mLink with either a static URL
(optimized) if the visitor is robot or
with dynamic URL if visitor is a
human user.

Every URL should be SEO friendly

as all the URLs are generated using
CatalogItemLinkDroplet. Also
since most of the robots dont
crawl more than 100kb of
information from a web page, all
the large images on the page will
be shown only to the human users
and not to the crawlers (robots).

2 CategoryDirectTemplate /atg/repository/seo/CategoryDi This Droplet generates URLs for

rectTemplate categories mapping directly into
the web application. URLs created
via this template should not
require forwarding by a jump
servlet. In easy term, this droplet
creates URL for human users.

3 CategoryIndirectTempla /atg/repository/seo/ This Droplet generates static URL

te CategoryIndirectTemplate for categories based on a
predefined template. In easy term,
this droplet generates URL for
search engine robots. The URLs
generated here are optimized
URLs.

4 ProductDirectTemplate /atg/repository/seo/ This Droplet generates URLs for

ProductDirectTemplate products mapping directly into the

ATG Page 93
 ATG Framework and Components

web application. URLs created via

this type of template should not
require forwarding by a jump
servlet. In easy term, this droplet
creates url for human users.

5 ProductIndirectTemplat /atg/repository/seo/ This Droplet generates static URL

e ProductIndirectTemplate for products based on a
predefined template. In easy term,
this droplet generates url for
search engine robots. The URLs
generated here are optimized.

6 CategorySitemapGener /atg/sitemaps/CategorySitema This component generates

ator pGenerator category sitemap xml with
optimized URLs of all categories
available in catalog repository.
This xml contain optimized URLs of
all categories in product catalog.

7 ProductSitemapGenerat /atg/sitemaps/ProductSitemap This component generates

or Generator product sitemap xml with
optimized URLs of all products
available in catalog repository.
This xml contain optimized URLs of
all products in product catalog.

8 StaticSitemapGenerator /atg/sitemaps/StaticSitemapGe This component generates

nerator sitemap xml with optimized URLs
of all static pages like contactUs
etc.

9 SitemapIndexGenerator /atg/sitemaps/SitemapIndexGe This component generates the

nerator entries in the SitemapRepository &
that will be used to create
siteIndex xml file.

10 SitemapGeneratorServi /atg/sitemaps/SitemapGenerat This component manages the

ce orService process of scheduling and invoking
various sitemap generator
components.

11 SitemapWriterService /atg/sitemaps/SitemapWriterS This component creates XML files

ATG Page 94
 ATG Framework and Components

ervice from SitemapRepository.

12 CanonicalItemLink /atg/repository/seo/ This droplet generates canonical

CanonicalItemLink url for products and Categories.

ATG Page 95
 ATG Framework and Components

JumpServlet
Jump servlet is the servlet placed in DAFPipeline which sense for keyword jump in request URL. If
found then request will be processed by JumpServlet. As mentioned earlier that we show optimized
URLs to search engine robots. These optimized URLs contain jump keyword.

We make sure that search engine is indexing optimized URLs only and same is shown to user. Hence
user comes to our website with optimized URLs (i.e. with the keyword jump) and JumpServlet translate
this URL to original (non-optimized) URL to process user request.

Example:

URL that is indexed by search engine looks like below.

http://mywebsite.com/root/jump/productname/productDetail/prod450074

JumpServlet translate the above URL in to non-optimized URL like shown below to process the request.

http://mywebsite.com/root/US/standardPDP/pdp.jsp?productId=prod450074&skuId=sku400068

JumpServlet Configuration
Jump Servlet component is present at path /atg/dynamo/servlet/dafpipeline. Jump servlet needs to be
defined in web.xml of commerce application.

Whenever request comes via indirect URL (optimized URL with jump keyword) then jump servlet
translate it to direct URL. Jump Servlet uses direct URL template to translate indirect URL to direct URL.

Note: - Direct URL means non-optimized URL and indirect URL means optimized URL with jump keyword.

Also add jump servlet to initial.properties so that servlet is ready to serve with the server startup.

ATG Page 96
 ATG Framework and Components

URL Optimization
URL optimization technique is to create neat and clean URL for robot visitor. If system detects the visitor
is search engine crawler then application renders optimized URLs (clean URL). This increases the
possibility of improving the ranking of page. We can achieve Url Optimization using following steps.

Make sure your URL contains important keywords such that it matches user search teams. Try to include
product name & important attributes in URL.

JSP Coding
When robot crawl the page then we have to show clean URLs. Following component on the JSP checks
for user agent (i.e. human or robot) and renders the URLs accordingly.

Considering that we are generating the URL for a category here. Param element showing in following
example is the category object.

Same coding snippet will be used to generate optimized URL for Product. If user agent is robot than URL
looks like below.

http://mywebsite.com/mycontextroot/jump/Motorola-Milestone/productDetail/prod450074

Note: - URL formed above is perfectly according the indirect template defined for Product and Category.
We will discuss these components in coming section.

Component Configuration
In order to achieve URL optimization we have to configure the bunch of components.

CategoryIndirectTemplate
This component gets called when CatalogItemLink droplet executed on JSP. Configurations of important
attributes are shown below.

ATG Page 97
 ATG Framework and Components

urlTemplateFormat
This property defines the format of indirect (optimized URL) URL. Example is shown above. Point to
remember here is it should contain keyword jump. As JumpServlet looks for keyword jump in the URL
and if found then convert the URL to direct (non-optimized) URL for the processing.

Actual URL looks like below by applying above format.

http://mywebsite.com/mycontextroot/jump/MobilePhone/categorycat170064

indirectRegex
This property defines the regex for your URL format. It checks if URL formed according to regular
expression defined here. This is mostly for validation purpose and to ensure that URL format and regex
are in sync.

regexElementList
This property is to support above two properties i.e. urlTemplateFormat & indirectRegex. We use item
in URL format. Hence we define the item here. What is the source of item and how to get their value.

In above example you can see that item is defined as Category and that is coming from ProductCatalog
repository.

Note: - There are many other properties available in this component. Kindly check the ATG document
for complete list of attributes

CategoryDirectTemplate
This component is used to generate direct URL (non-optimized) for human users. As user visit the page
on the site then CatalogItemLink droplet gets executed. This droplet checks the user profile and makes
internal call to respective template (Direct or Indirect) component to form and render URL.

If the visitor is human user then CatalogItemLink droplet makes call to CategoryDirectTemplate to form
direct URL. Following is the configuration of this component.

ATG Page 98
 ATG Framework and Components

Refer above section to know about property urlTemplateFormat.

CategoryTemplateMapper
This component keeps the list of URL templates defined in the system. We can define custom Direct /
Indirect URL template component. These template components will not be considered to form desired
URL unless they are listed in templates property of CategoryTemplateMapper for item type Category.
Kindly see the configuration below.

templates
This property is list type of property that contains the list of templates defined. Templates get resolved
by using the item type and visitor profile.

Example: if visitor is human and item is category then CategoryDirectTemplate will be used to form URL
hence direct URL (non-optimized) gets formed.

But if visitor is robot (crawler) and item is category then CategoryIndirectTemplate will be used to form
URL hence indirect URL (optimized) gets formed.

Note: - We have discussed above URL optimization for Item type Category. We need same set of
components and configuration for Item type Product. Hence I am not documenting the configuration for
Product item. Following are the name of important components for item type Product.

ProductDirectTemplate
Refer CategoryDirectTemplate section above.

ProductIndirectTemplate
Refer CategoryIndirectTemplate section above.

ProductTemplateMapper
Refer CategoryTemplateMapper section above.

ATG has created all SEO components considering two basic Item types i.e. Product and Category
because we mostly want to optimize the URL of product and category items. If the project requirement
is also to optimize the URL of custom items (other than Product and Category) then you can define
similar set of components by using the existing OOB java classes and do the configuration to generate
respective direct and indirect URLs.

ATG Page 99
 ATG Framework and Components

Meta Tag Implementation

Web search engines ranking of page is partly based on the words that appear in certain HTML tags,
particularly <meta> tags and the <title> tag. A common SEO technique is to list key search terms in these
tags, to raise the ranking of the pages of our site.

Due to large number of pages in the website, it is not feasible to provide data manually for these tags for
every page exist. We can populate or update these tags dynamically from BCC (publishing).

SEO tag repository is used to store meta tag data i.e. keywords, description and title for every page
exist in the website. This data will be retrieved and meta tags will be populated with the relevant
keywords, description and title information. Primary key to retrieve this data from the SEO repository is
url of the page.

Admin user has to populate meta tag data very first time in SEO repository from BCC (publishing) for
every page in the website.

JSP Coding
JSP coding is needed to fetch meta tag data i.e. title, keyword and description information for given
page. Here the key to fetch this data from SEO repository is the page URL. Idea here is to generate meta
tags for every main JSP with unique title, description and keyword information. If we dont provide
unique data to title, description and keyword for given pages then Crawler consider them all as a single
page though their body content is different & therefore ranking of the page comes down.

This data will be controlled by merchandising user from BCC (publishing) application.

You can create a JSP fragment with the following piece of code and include the same in the header
section of all other JSPs. In this way same code snippet can be used and effort can be saved.

ATG Page 100

 ATG Framework and Components

You can further tweak the above code by appending the product / category name in title information
coming from repository. You can fetch information from repository like shown above and append
product name in it. By appending product name in title and description, you are making the virtual
unique pages & increasing the chance of getting indexed.

Example

For Product Nokia X101, title looks like below

Product Detail Page Nokia X101

Product Motorola AY203, title looks like below

Product Detail Page Motorola AY203

Assume ProductDetail page is served by productDetail.jsp in your WAR. Same JSP is used to render the
information for Nokia and Motorola products. This JSP has meta tags (title etc). As shown above, by
appending the product name in title information coming from SEO Repository, we are making many
unique virtual pages at run time.

Pages rendered for different products consider as unique page because their title are different. Hence
crawler will index them all. That means the number of pages in your website is equal to number of
products in your catalog. That also means search engine have found tons of valuable information in
website for indexing.

But if we dont append product name than title looks same for all products hence crawler consider them
as single (same) page though they are showing different products information.

ATG Page 101

 ATG Framework and Components

Canonical URL
Canonical URLs are the outcome of the process of normalization of the URLs to make them consistent
across the site. The process includes converting unfriendly URL to SEO friendly URL so that search
engines index the page with the product name appearing in URL.

For example:

The URL before normalization look like,

http://mywebsite.com/mycontextroot/country/productDetails.jsp?productId=prd10002

And after normalization same look like this,

http://mywebsite.com/mycontextroot/jump/Motorola-Milestone-XT720-black/productDetail /prod450074/cat17006

For SEO using Canonical URLs technique, application should specify the link tag on product detail page
which specifies the canonical URL on the page. This link tag can be specified like below,

<link rel="canonical" href="http://mywebsite.com/mycontextroot/jump/Motorola-Milestone-XT720-

black/productDetail/prod450074/cat170064"/>

The canonical URL is similar to static URL. When a web spider accesses the page using static URLs it finds
a link on the page and gets indexed. Human user gets this URL as search results (search engine) and they
comes to the site by clicking the same, jump servlet translate this URL to dynamic URL (non-optimized)
and request is processed.

JSP Coding
We have to put canonical URL on product detail page and category summary page. Idea here is to have
direct URL for product detail page and category summary page for web spider.

Put the following piece of code in header section of Product Detail JSP and category summary page.

Component Configuration
You need to configure component i.e. CanonicalItemLink droplet to render canonical URL for product
item type. Refer following configuration and put this configuration in CanonicalItemLink droplet
component.

ATG Page 102

 ATG Framework and Components

itemDescriptorNameToUrlTemplateMap
This is map property that contains item to indirect template mapping. Hence if item is Product then
ProductIndirectTemplate component is used to form canonical URL. Same applies for item type
Category.

defaultRepository
It takes reference of repository where item belongs to.

ATG Page 103

 ATG Framework and Components

Sitemap Generation
Sitemaps are files stored on a web server that list the URLs of useful pages available in our website, so
web spiders are able to identify site content without relying exclusively on their ability to crawl and
parse the pages. Sitemaps are not an official standard, but they are supported by many search engines,
including Google, Yahoo and MSN.

Sitemap is an xml file that list URLs of all pages in your website. It contains basic information like URL,
lastModified, changeFrequency and priority about the page. Sample entry in sitemap xml is shown
below.

Sitemap Configuration
We need to create & configure certain components to generate appropriate sitemap xml files for our
commerce website. As commerce website always have long list of categories and infinite products. It is
good to generate unique URLs for all these items and put them all in sitemap xml file. More URLs in
sitemap drives more indexing of data from the site and increases the chance of higher ranking.

1. Create component XXXXSiteMap at the following path in your ATG module. Here XXXX stands
for your application context root in capital letters.

<ATG_HOME>/YourModule/config/atg/registry/webappregistry/XXXXSiteMap.properties

2. Now add following configuration in the above created component properties file.

Here XXXX stands for application context root.

3. Create component XXXXWebApp at the following path in your ATG module. Here XXXX stands
for your application context root in capital letters.

<ATG_HOME>/YourModule/config/atg/registry/webappregistry/XXXXWebApp.properties

ATG Page 104

 ATG Framework and Components

4. Now add following configuration in above created component properties file.

Here XXXXEar is the name of application EAR and xxxx is context root of application.

5. Now configure ProductSitemapGenerator component. This component is responsible for

generating Sitemap xml for item type Product. This component is present at the following path.

<ATG_HOME>/YourModule/config/atg/sitemap/ProductSitemapGenerator.properties.

Following attributes are needed to be configured for this component.

sourceRepository - repository to retrieve information for generator.

contextCatalog - catalog id that will be used for resolving derived properties

sitemapFilePrefix Prefix for your Sitemap xml file. Sitemap file must have no more than 50,000
URLs and must be no larger than 10MB (10,485,760 bytes). If we list more pages (URL) than this
limitation, then generator will split information into several files with names
sitemapFilePrefix_1.xml, sitemapFilePrefix_2.xml and so on.

changeFrequency - How frequently the page is likely to change. Valid values are: always, hourly,
daily, weekly, monthly, yearly, never.

Priority - The priority of this URL relative to other URLs on your site. Valid values range from 0.0
to 1.0.

urlPrefix - URL prefix with protocol, host, port and context path. Context path should not be
included here if webApp property is specified.

webApp - Used to retrieve application's context root.

itemDescriptorName - Type of repository item to retrieve.

Template - Generator uses this template to construct sitemap URL for repository item of type
ItemDescriptorName Both direct and indirect templates can be set here. Use indirect template
to generate sitemap with optimized URLs for repository items.

Sample configuration of this component is shown below.

ATG Page 105

 ATG Framework and Components

6. Now configure CategorySitemapGenerator component. This component is responsible for

generating Sitemap xml for item Category. The configuration is exactly same as shown above for
item type Product. This component is present at the following path.

<ATG_HOME>/YourModule/config/atg/sitemap/CategorySitemapGenerator.properties.

Note: - You need to configure this component according to your environment setup.

7. Now configure StaticSitemapGenerator component. This component is responsible for

generating the sitemap for static pages in your website like contact us etc.

Here property staticPages maintains the list of static pages in your website.

ATG Page 106

 ATG Framework and Components

8. Now configure SiteMapIndexGenerator component. This component is responsible for storing

the sitemap data in repository. This component also creates a list of sitemaps generated
according to the configuration. This is available at the following path.

<ATG_HOME>/YourModule/config/atg/sitemap/SitemapIndexGenerator.properties.

9. Now configure SitemapGeneratorService component. This component is backbone for

generating Sitemaps. This component generates sitemap according to the configuration done in
respective generators (i.e. ProductSitemapGenerator etc).

If we define new Generator (for new item type) then it is mandatory to add the same in
sitemapGenerators list property of this component else sitemap will not be generated for new
Generator added.

Property warDir is the property that takes absolute path of folder to place sitemap xml files
generated. Ideally this should be the root of your application WAR.

ATG Page 107

 ATG Framework and Components

10. Now configure final component i.e. SitemapWriterService. This component is responsible for
writing down the sitemaps data in to XML files at the configured path.

We are done with all required configuration for sitemap. Now we are ready to generate first set of
Sitemap xmls. Refer following section for the same.

Steps to Generate Sitemap

1. Make sure commerce (production) server is up and running. Also ensure the access to
/dyn/admin application.

2. Go to /dyn/admin application. Provide user and password to enter in to application.

http://mywebsite.com/dyn/admin

3. Go to Sitemap Administration Generate sitemap Start service.

4. After the generation of the sitemap, invoke the Sitemap Writer service to write to xml files.

Sitemap Administration Write Sitemaps Start service.

5. Now you can find the SiteMap xml files are generated at the configured path. To know the path,
check the value of warDir property of component SitemapGeneratorService.

ATG Page 108

 ATG Framework and Components

Appendix
Droplets
Following are the extensively used droplets. Please refer the ATGPageDevGuide.pdf for the detail.

atg.droplet.ErrorMessageForEach
Displays error messages that occur during a form submission. (ATGPageDevGuide.pdf, 257)

atg.droplet.For
Displays a single output the number of times specified. (ATGPageDevGuide.pdf, 261)

atg.droplet.ForEach
Displays each element of an array. (ATGPageDevGuide.pdf, 263)

atg.repository.servlet.ItemLookupDroplet
Looks up an item in one or more repositories based on the items ID, and renders the item on the page.
(ATGPageDevGuide.pdf, 280)

atg.targeting.RepositoryLookup
Looks up an item in a specific repository, based on the items ID, and renders the item on the page.
(ATGPageDevGuide.pdf, 320)

atg.repository.servlet.RQLQueryForEach
Constructs an RQL query and renders its output parameter once for each element returned by the
query. (ATGPageDevGuide.pdf, 322)

atg.droplet.Switch
Displays one of several possible outputs, depending on input parameter value. (ATGPageDevGuide.pdf,
340)

atg.droplet.TableForEach
Displays each element of an array, arranging the output in a two-dimensional format.
(ATGPageDevGuide.pdf, 342)

atg.targeting.TargetingArray
TargetingArray differs from the others in that it does not format the output of the targeting operation.
Instead, you must use another servlet bean to format the outputCategoryLookup.
(ATGPageDevGuide.pdf, 350)

atg.targeting.TargetingFirst
Displays the first n items, where n is a number you specify. (ATGPageDevGuide.pdf, 352)

ATG Page 109

 ATG Framework and Components

atg.targeting.TargetingForEach
Displays all of the items returned by the targeter. (ATGPageDevGuide.pdf, 355)

atg.targeting.TargetingRandom
Displays n items chosen randomly. (ATGPageDevGuide.pdf, 358)

atg.targeting.TargetingRange
Displays a range of items, such as the third through the seventh. (ATGPageDevGuide.pdf, 360)

ProductLookup

SkiwLookup

CatalogItemLookupDroplet

RepriceOrderDroplet

PriceEachItem

PriceItem

ShippingGroupsDroplet

PaymentGroupsDroplet

PriceItemDroplet

RepriceOrderDroplet

/atg/commerce/gifts/GiftlistLookupDroplet

/atg/commerce/gifts/GiftlistDroplet

atg.commerce.gifts.GiftitemDroplet

ATG Page 110

 ATG Framework and Components

Form Handlers

SimpleSQLFormHandler

ShoppingCartModifier

ExpressCheckoutFormHandler

CartModifierFormHandler

GiftListFormHandler

GiftListSearch

ATG Page 111