ATG Framework and Components
ATG Page 1
e-Com
ATG Framework and ComponentPawan Modi
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 2
Table of Contents
ABBREVIATION
7
ATG
8
Introduction 8 ATG Architectures 8Component 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
ATG Page 3
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
ATG Page 4
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.
ATG Page 5
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 6
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
ATG Page 7
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 8
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 9
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 Page 10
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.
ATG Page 11
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 industry’s leading J2EE application servers, including ATG’s 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 12 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 13 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 14 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 Page 15
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 16
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,
ATG Page 17 • 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 18
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.
ATG Page 19 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 20 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 21
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.
ATG Page 22
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 repository’s 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 table’s primary key. If we don’t 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 23
Types of Repository in ATG
The following Repository models exist in ATG.
1. SQL Repositories - use ATG’s 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 24 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 25 – 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 26 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.
ATG Page 27 • 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.
ATG Page 28 • 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 view’s 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.
ATG Page 29 • 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 item’s 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 30 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 31
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.
ATG Page 32
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 JSP’s 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 33
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 34 Example of Custom Droplet (JSP Code)
TargetingForEach
TargetingForEach droplet uses the RootCategories targeter to find root categories.
CategoryLookup, ProductLookup , SKULookup
Categories, products and sku’s can be displayed with the help of CategoryLookup, ProductLookup and SKULookup droplets respectively.
ItemLookupDroplet
RepriceOrderDroplet, PriceEachItem, PriceItem
ATG Page 35
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 component’s property. • Dynamically setting values to component’s 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 36
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.
ATG Page 37 • 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 38
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
ATG Page 39
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 40
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 that’s 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 41 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 that’s 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 42 • 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 43 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 Servlet1’s nextServlet property and rewrites Servlet1’s 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 component’s property file.
4. For example, if you want your servlet to follow the DynamoServlet in the pipeline, use
ATG Page 44
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 45
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.
2
If we want to personalize content as a result of a site visitor's doing something specific (for example, logging in), use a scenario.
The business rules we can set up through targeters are more flexible in some cases than scenarios. For this reason, if we need to set up highly complex rules to match content to visitors, use targeters.
3
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
content). Targeters don’t use slots.
4
If we want to set up a long-term approach to content and visitor management, use