eCommerce Integration Framework

eCommerce, together with Product Information Management (PIM), handles the activities of a website focused on selling products via an online store:

• Creation, lifetime, and obsolescence of a product
• Price management
• Transaction management
• Live and centralized storage records
• Web interfaces

AEM eCommerce helps marketers deliver branded, personalized shopping experiences across web, mobile, and social touchpoints. The AEM authoring environment allows you to customize pages and components based on target visitor context and merchandising strategies; for example:

• product pages
• shopping cart components
• checkout components

The implementation allows real-time access to product information. This can be used to enforce:

• product information integrity
• pricing
• stock-keeping inventory
• variations in state of a shopping cart
  

AEM eCommerce provides:

AEM native eCommerce is available as part of a standard installation and provides you with the full functionality of the eCommerce framework.

AEM Native eCommerce:

• Provides:
  • User views (provided by out-of-the-box AEM components) for Product Information, Shopping Cart and Checkout.
  • Shopping cart and checkout information.
  • Search Engine Optimization (SEO).
  • Community functionality.
  • Unstructured marketing interactions.
  • Product Information from the internal database (JCR); located under:
        /etc/commerce/products
  • Product variant management.
  • Search within the product information.
  • Promotions and Vouchers for personalized shopping.
• Processes:
  • The Shopping Cart.
  • The Checkout.

This means that:

• Shoppers can register and shop without waiting.
• Price changes will be seen by shoppers without delay.
• Products can be added as required.
• Campaigns (whether promotions, vouchers or teasers) provide personalized shopping.

The following components and pages can use eCommerce data:

• Landing page
  Rendered by AEM (Commerce Category).
  This provides primarily static information, for example, an introduction and overview with links to the underlying product pages.
  
• Product
  Rendered by AEM (Commerce Product).
  Dynamic information about individual products; for example, price changes, special offers. Updates from live data are reflected. Product catalogs contain both hierarchical section pages and the individual product pages.
  The product component can be added to any page where the parent page delivers the required metadata (i.e. the paths to cartPage and cartObject). In Geometrixx Outdoors this is supplied by UserInfo.jsp.
• Search results / product lists (cached)
  See search; this component can be added to any page.
  
• myAccount
  Transaction data is combined with personal information about the shopper. AEM uses some of this data as profile data.
  
• Checkout
  Checkout is implemented with standard AEM forms. This allows the marketing manager to customize the experience with marketing content.
• Shopping cart
  AEM renders this information using the appropriate components.
• Promotions and Vouchers
  You can create vouchers and promotions that customers can then use in their shopping cart to claim the appropriate discount.

AEM eCommerce caters for the following roles to maintain the data:

• Product Information Management (PIM) User who maintains:
  
  • Product information.
  • Taxonomy, categorization, approval.
  • Interacts with digital asset management.
  • Pricing - often this comes from an ERP system and is not explicitly maintained in the commerce system.
• Author / Marketing Manager who maintains:
  • Marketing content for all channels.
  • Promotions.
  • Vouchers.
  • Campaigns.
• Surfer / Shopper who:
  • Views your product information.
  • Places items into the shopping cart.
  • Checks out their orders.
  • Expect order fulfillment.

With AEM native eCommerce product data is maintained in CRX:

    /etc/commerce/products

and made available in AEM.

For appropriate products information about variants can also be held. For example, for items of clothing the different colors available are held as variants:

Vouchers are a tried and tested method of offering discounts to either attract customers into making a purchase and/or rewarding customer's loyalty.

Promotions, together with vouchers, allow you to realize scenarios such as:

• A company provides custom prices for employees, which is a handcrafted list of users.
• Long-term customers receive discounts on all orders.
• A sale price offered over a well-defined time period.
• A customer receives a voucher when their previous order exceeded a specific amount.
• A customer who buys product-X is offered a discount on product-Y (pair products).
  

With AEM native eCommerce you can create vouchers and promotions that customers can then use in their shopping cart to claim the appropriate discount.

• Vouchers:
  • A Voucher is a page-based component that is created / edited with the Websites console.
  • Vouchers supply:
    • A voucher code (to be typed into the cart by the shopper).
    • A voucher label (to be displayed after the shopper has entered it into the cart).
    • A promotion path (which defines the action the voucher applies).
  • External commerce engines can also supply vouchers.
    
  • The Voucher component provides:
    • A renderer for voucher administration; this shows any vouchers currently in the cart.
      
    • The edit dialogs (form) for administrating (adding/removing) the vouchers.
    • The actions required for adding/removing vouchers to/from the cart.
  • Vouchers do not have their own on and off date/times, but use those of their parent campaigns.
• Promotions:
  • A Promotion is a page-based component that is created / edited with the Websites console.
  • Promotions supply:
    • A priority
    • A promotion handler path
  • You can connect promotions to a campaign to define their on/off date/times.
  • You can connect promotions to an experience to define their segments.
  • Promotions not connected to an experience will not fire on its own, but can still be fired by a Voucher.
  • The Promotion component contains:
    • renderers and dialogs for promotion administration
    • sub-components for rendering and editing configuration parameters specific to the promotion handlers

In AEM:

• a campaign specifies the on/off times
• experiences within the campaign are used to group assets (teaserpages, promotions, etc) according to the audience segment they correspond to

A promotion can be held either in an experience or directly in the campaign:

• If a promotion is held in an experience, then it can be automatically applied to an audience segment.
  For example, in the geometrixx-outdoors sample site, the promotion:
       /content/campaigns/geometrixx-outdoors/big-spender/ordervalueover100/free-shipping
  is in an experience, and so fires automatically whenever the segment (ordervalueover100) resolves.
• If a promotion does not appear within an experience (only in the campaign), then it cannot be automatically applied to an audience.  However, it can still be fired if the shopper enters a voucher into their cart and that voucher references the promotion.
  For example, the promotion:
       /content/campaigns/geometrixx-outdoors/article/10-bucks-off
  is outside an experience and so never fires automatically (ie: based on segmentation).  It is, however, referenced by the vouchers which can be found in several of the experiences within the article campaign.  Entering those voucher codes into the cart will result in the promotion firing.

Since the AEM native implementation uses standard pages for products, you can use the standard search component to create a search page.

If you require a more thorough implementation, you can either:

• Extend the default search component with the functionality you need.
• Implement the search method in your CommerceService and then use the eCommerce search component on your search page.

Payment details, including credit card information, is managed by AEM, then forwarded to a payment processing system.

Payment Card Industry (PCI) complicance can be achieved.

AEM supports product content in multiple languages. When requesting data from the database, the integration framework retrieves the language from the current tree (for example, en_US for pages under /content/geometrixx-outdoors/en_US).

For a multi-lingual store, you can import your catalog in each language tree individually (or copy it by means of MSM).

The product catalog sections provide you with, for example:

• an introduction (image and/or text) to the category; this can also be used for banners and teasers to promote special offers
  
• links to the individual products in that category
• links to the other categories

An AEM page (for example, using the Commerce Product template) can provide:

• general product information; text and images
  
• pricing

And allow the shopper to select:

• color and size variants
• quantity
  
• add to basket

The shopping cart provides:

• an overview of items selected
• links to the individual product pages
• updates to quantity
• removal of the item

AEM native stores the cart in a cookie so items stay in the cart across log-in/log-out. Price changes are reflected as they occur.

Often sign-up is required for the shopper to have access to the shopping cart. If so, this requires registration so that a customer-specific account can be created.

After sign-up the shopper must login with their account so that their actions can be tracked and their orders fulfilled.

In order to make a voucher unavailable to customers, you can either:

• Deactivate the voucher - it will remain available on the author environment so you can re-activate it at a later time.
• Delete it completely.

Both actions can be done from the Websites console.

To change the properties of a voucher or promotion, you can double-click on it on the Websites console and click Edit. After saving it, you should activate it so that the changes get pushed to the publish instance(s).

To allow users to add vouchers to their carts, you can use the built-in Vouchers component (Commerce category). You need to add this to the same page as where the cart is displayed (but is not mandatory). The vouchers component is merely a form in which the user can enter a voucher code, it is the shopping cart component that actually shows the list of applied vouchers and their discount.

In the demo site (Geometrixx Outdoors - English) you can see the voucher form on the cart page, under the actual shopping cart.

The integration framework includes an integration layer with an API. This allows you to build AEM components for eCommerce capabilities (independent of your specific eCommerce engine). It also allows you to use the internal CRX database or to plug in an eCommerce system and pull product data into AEM.

A number of out-of-the-box AEM components are provided to use the integration layer. Currently these are:

• A product display component
• A shopping cart
• Promotions and vouchers
  
• Catalog and section blueprints
  
• Check-out
• Search

For search an integration hook is provided that allows you to use the AEM search, a third party search (like Search&Promote) or a combination thereof.

The eCommerce framework can be used with any eCommerce solution, the engine being used needs to be identified by AEM - even when using the AEM native engine:

• eCommerce Engines are OSGi services supporting the CommerceService interface
  • Engines can be distinguished by a commerceProvider service property
• AEM supports Resource.adaptTo() for CommerceService and Product
  • The adaptTo implementation looks for a cq:commerceProvider property in the resource's hierarchy:
    • If found, the value is used to filter the commerce service lookup.
    • If not found, the highest-ranked commerce service is used.
  • A cq:Commerce mixin is used so the cq:commerceProvider can be added to strongly-typed resources.
• The cq:commerceProvider property is also used to reference the appropriate commerce factory definition.
  • For example, a cq:commerceProvider property with the value geometrixx will correlate to the OSGi configuration for Day CQ Commerce Factory for Geometrixx-Outdoors (com.adobe.cq.commerce.hybris.impl.GeoCommerceServiceFactory) - where the parameter commerceProvider also has the value geometrixx.
    
  • Here further properties can be configured (when appropriate and available).
    

In a standard AEM installation a specific implementation is required, for example:

A session to store information related to the customer's shopping cart.

The CommerceSession:

• Owns the shopping cart
  • performs add/remove/etc
  • performs the various calculations on the cart;
    commerceSession.getProductPriceInfo(Product product, Predicate filter)
• Owns persistance of the order data:
      CommerceSession.getUserContext()
• Can retrieve/update delivery details by using updateOrder(Map<String, Object> delta)
• Also owns the payment processing connection
• Also owns the fulfillment connection

A single product can have multiple variations; for instance, it might vary by color and/or size. A product must define which properties drive variation; we term these variant axes.

However, not all properties are variant axes. Variations can also affect other properties; for example, the price might be dependant on size. These properties cannot be selected by the shopper and therefore are not considered variant axes.

Each product and/or variant is represented by a resource, and therefore maps 1:1 to a repository node. It is a corollary that a specific product and/or variant can be uniquely identified by its path.

Any product resource can be represented by a Product API. Most calls in the product API are variation specific (although variations might inherit shared values from an ancestor), but there are also calls which list the set of variations (getVariantAxes(), getVariants(), etc.).

In general:

• PIM data is located under /etc
  
• Product references under /content.

There must be a 1:1 map between product variations and product data nodes.

Product references must also have a node for each variation presented - but there is no requirement to present all variations.  For instance, if a product has S, M, L variations, the product data might be:

While a "Big and Tall" catalog might have only:

Finally, there is no requirement to use product data.  You can place all product data under the references in the catalog; but then you cannot really have multiple catalogs without duplicating all the product data.

API

• General Storage Mechanism
  • Product nodes are nt:unstructured.
  • A product node can be either:
    • A reference, with the product data stored elsewhere:
      • Product references contain a productData property, which points to the product data (typically under /etc/commerce/products).
      • The product data is hierarchical; product attributes are inherited from a product data node's ancestors.
      • Product references can also contain local properties, which override those specified in their product data.
    • A product itself:
      • Without a productData property.
      • A product node which holds all properties locally (and does not contain a productData property) inherits product attributes directly from its own ancestors.
• AEM-native Product Structure
  • Each variant must have its own leaf node.
  • The product interface represents both products and variants, but the related repository node is specific about which it is.
  • The product node describes the product attributes and variant axes.

Components

• The shopping cart is owned by the CommerceSession:
  • The CommerceSession performs add, remove, etc.
  • The CommerceSession also performs the various calculations on the cart.
  • The CommerceSession also applies vouchers and promotions that have fired to the cart.
• While not directly cart-related, the CommerceSession must also provide catalog pricing information (since it owns pricing)
  • Pricing might have several modifiers:
    • Quantity discounts.
    • Different currencies.
    • VAT-liable and VAT-free.
  • The modifiers are completely open-ended with the following interface:
    • int CommerceSession.getQuantityBreakpoints(Product product)
    • String CommerceSession.getProductPrice(Product product)

Storage

• Storage
  • In the AEM-native case carts of are stored in the ClientContext

Personalization

• Personalization should always be driven through the ClientContext.
• A ClientContext /version/ of the cart is created in all cases:
  • Products should be added by using the CommerceSession.addCartEntry() method.
• The following illustrates an example of cart information in the ClientContext cart:

Cart and Order Data

The CommerceSession owns the three elements:

1. Cart contents
2. Pricing
3. The order details

Shipping Calculations

• Order forms often need to present multiple shipping options (and prices).
• The prices might be based on items and details of the order, such as weight and/or delivery address.
• The CommerceSession has access to all the dependencies, so it can be treated in a similar manner as product pricing:
  • The CommerceSession owns shipping pricing.
  • Use updateOrder(Map<String, Object> delta) to retrieve/update delivery details.

Following the standard service API model, the eCommerce project provides a set of search-related APIs that can be implemented by individual commerce engines.

The eCommerce project contains a default search component, located in:

    /libs/commerce/components/search

This makes use of the search API to query the selected commerce engine (see eCommerce Engine Selection):

There are several generic / helper classes provided by the core project:

1. CommerceQuery
   Is used to describe a search query (contains information about the query text, current page, page size, sort and selected facets). All eCommerce services that implement the search API will receive instances of this class in order to perform their search. A CommerceQuery can be instantiated from a request object (HttpServletRequest).
2. FacetParamHelper
   Is a utility class that provides one static method - toParams - that is used for generating GET parameter strings from a list of facets and one toggled value. This is useful on the UI side, where you need to display a hyperlink for each value of each facet, such that when the user clicks on the hyperlink the respective value is toggled (i.e. if it was selected it is removed from the query, otherwise added). This takes care of all the logic of handling multiple/single-valued facets, overriding values, etc.

The entry point for the search API is the CommerceService#search method which returns a CommerceResult object. See the API Documentation for more information on this topic.

• Vouchers:
  • A Voucher is a page-based component that is created / edited with the Websites console and stored under:
         /content/campaigns
  • Vouchers supply:
    • A voucher code (to be typed into the cart by the shopper).
    • A voucher label (to be displayed after the shopper has entered it into the cart).
    • A promotion path (which defines the action the voucher applies).
  • Vouchers do not have their own on and off date/times, but use those of their parent campaigns.
  • External commerce engines can also supply vouchers; these require a minimum of:
    • A voucher code
    • An isValid() method
  • The Voucher component (/libs/commerce/components/voucher) provides:
    • A renderer for voucher administration; this shows any vouchers currently in the cart.
      
    • The edit dialogs (form) for administrating (adding/removing) the vouchers.
    • The actions required for adding/removing vouchers to/from the cart.
• Promotions:
  • A Promotion is a page-based component that is created / edited with the Websites console and stored under:
         /content/campaigns
  • Promotions supply:
    • A priority
    • A promotion handler path
  • You can connect promotions to a campaign to define their on/off date/times.
  • You can connect promotions to an experience to define their segments.
  • Promotions not connected to an experience will not fire on its own, but can still be fired by a Voucher.
  • The Promotion component (/libs/commerce/components/promotion) contains:
    • renderers and dialogs for promotion administration
    • sub-components for rendering and editing configuration parameters specific to the promotion handlers
  • Two promotion handlers are supplied out of the box:
    • DiscountPromotionHandler, which applies a cart-wide absolute or percentage discount
    • PerfectPartnerPromotionHandler, which applies a product absolute or percentage discount if the partner procduct is also in the cart
  • The ClientContext SegmentMgr resolves segments and the ClientContext CartMgr resolves promotions. Each promotion that is subject to at least one resolved segment will be fired.
    • Fired Promotions are sent back to the server via an AJAX call to re-calculate the cart.
    • Fired Promotions (and added Vouchers) are also shown in the ClientContext panel.

Adding/Removing a voucher from a cart is accomplished via the CommerceSession API:

This way, the CommerceSession is responsible for checking whether a voucher exists and if it can be applied or not. This might be for vouchers that can only be applied if a certain condition is met; for example, when the total cart price is greater than $100). If a voucher cannot be applied for any reason, the addVoucher method will throw an exception. Also, the CommerceSession is responsible for updating the cart's price(s) after a voucher is added / removed.

The Voucher is a bean-like class that contains fields for:

• Voucher code
• A short description
• Referencing the related promotion that indicates the discount type and value

The AbstractJcrCommerceSession provided can apply vouchers. The vouchers returned by the class getVouchers() are instances of cq:Page containing a jcr:content node with the following properties (amongst others):

• sling:resourceType (String) - this needs to be commerce/components/voucher
• jcr:title (String) - for the voucher's description
• code (String) - the code the user has to enter to apply this voucher
• promotion (String) - the promotion to be applied; e.g. /content/campaigns/geometrixx-outdoors/article/10-bucks-off

Promotion handlers are OSGi services which modify the shopping cart. The cart will support several hooks that will be defined in the PromotionHandler interface.

Three promotion handlers are provided out of the box:

• DiscountPromotionHandler applies a cart-wide absolute or percentage discount
• PerfectPartnerPromotionHandler applies a product absolute or percentage discount if the product partner is also in the cart
• FreeShippingPromotionHandler applies free shipping

Deploying the necessary eCommerce packages will provide the full functionality of the eCommerce framework, together with a reference implementation of eCommerce functionality as provided with a hybris implementation (including a demonstration catalog)

This is available under the English (US) branch (/content/geometrixx-outdoors/en_US) of the Geometrixx Outdoors site:

• Product Information (with color variants when appropriate)
  
• Shopping Cart content overviews
• Customer Sign-Up and Customer Sign-In
• Access to the hybris management console

To install eCommerce functionality you need the following packages, available from Package Share:

• AEM eCommerce framework:
  • this is part of a standard AEM installation
    
• AEM hybris implementation:
  • cq-hybris-content
    
  • hybris-specific API implementation
  • a reference implementation to illustrate use of hybris (geometrixx-outdoors/en_US)
• Embedded, self-installing hybris server:
  
  • cq-hybris-server
  • this can be used for POCs, demos, etc.; it is not suitable for production
    

To deploy a fully-fledged configuration the basic steps are:

1. Install AEM.
2. Install the packages using the package manager:
   1. cq-hybris-content
   2. cq-hybris-server
3. Install your eCommerce engine (for this example, hybris).
   
4. Construct your catalog in your eCommerce engine.
5. Use the importer to import the catalog into a specific location in AEM.
6. Author any supplementary pages that you need in AEM.

The Catalog version (hybris.catalog.version) that is imported can be configured for:

Day CQ Commerce Factory for Hybris
(com.adobe.cq.commerce.hybris.impl.HybrisServiceFactory)

Catalog version is usually set to either Online or Staged (the default).

When working with AEM there are several methods of managing the configuration settings for such services; see Configuring OSGi for full details.  Also see the console for a full list of configurable parameters and their defaults.

The log output provides feedback on the created pages and components and reports potential errors.

The following listing shows a sample structure (of assets, pages and components) that is created by default:

Such a structure is created by the OSGi service DefaultImportHandler that implements the ImportHandler interface. An import handler is called by the actual importer to create products, product variations, categories, asset, etc.

The structure to be generated when importing can be configured for:

Day CQ Commerce Hybris Default Import Handler
(com.adobe.cq.commerce.hybris.importer.DefaultImportHandler)

When working with AEM there are several methods of managing the configuration settings for such services; see Configuring OSGi for full details.  Also see the console for a full list of configurable parameters and their defaults.

The configuration of the response parser defines which properties are loaded for (variant) products.

If you need to change the properties loaded from hybris, you need to update this list.

The response handler can be configured for:

Day CQ Commerce Hybris Response Parser
(com.adobe.cq.commerce.hybris.impl.importer.HybrisResponseParserImpl)

When working with AEM there are several methods of managing the configuration settings for such services; see Configuring OSGi for full details.  Also see the console for a full list of configurable parameters and their defaults.

The hybris catalog is periodically synchronized with AEM.

The interval for the importer to synchronize can be for:

Day CQ Commerce Hybris Catalog Importer
(com.adobe.cq.commerce.hybris.impl.importer.HybrisImporterImpl)

When working with AEM there are several methods of managing the configuration settings for such services; see Configuring OSGi for full details.  Also see the console for a full list of configurable parameters and their defaults.

The integration framework provides the mechanisms and components for:

• connection to an eCommerce system
• pulling data into AEM
• displaying that data and collecting the shopper's responses
• returning transaction details
• search over the data from both systems

This means that:

• shoppers can register and shop without waiting
• price changes will be seen by shoppers without delay
• products can be added as required

To optimize operation each application concentrates on its own area of expertise with information being transferred between the two in real time; for example:

• AEM:
  • Requests:
    • Product Information from hybris.
  • Provides:
    • User views for Product Information, Shopping Cart and Checkout.
    • Shopping cart and checkout information to hybris.
    • Search Engine Optimization (SEO).
    • Community functionality.
    • Unstructured marketing interactions.
• hybris:
  
  • Provides:
    • Product Information from the database.
    • Product variant management.
      
    • Search within the product information.
  • Processes:
    • The Shopping Cart.
    • The Checkout.
    • Order fulfillment.

A number of out-of-the-box AEM components are provided to use the integration layer. Currently these are:

• Product display component
• Shopping cart
• Check-out

Various search options are also available.

The following components and pages can use eCommerce data:

• Landing page
  Rendered by AEM (Commerce Category).
  This provides primarily static information, for example, an introduction and overview with links to the underlying product pages.
  
• Product
  Rendered by AEM (Commerce Product).
  Dynamic information about individual products; for example, price changes, special offers. Updates from live data are reflected.
  The product component can be added to any page where the parent page delivers the required metadata (i.e. the paths to cartPage and cartObject). In Geometrixx Outdoors this is supplied by UserInfo.jsp.
• Search results / product lists (cached)
  See search below. This component can be added to any page.
  
• myAccount
  Transaction data in hybris is combined with personal information about the shopper. AEM uses some of this data as profile data. A forms action in AEM is used to write information back to hybris.
• Checkout
  Checkout is implemented with standard AEM forms. This allows the marketing manager to customize the experience with marketing content.
  The checkout process is a very complex process that is hybris owned.
• Shopping cart
  hybris provides all relevant data (xml). AEM renders this information using the appropriate components.

The integrated system caters for the following roles to maintain the data:

• Product Information Management (PIM) User who maintains:
  
  • Product information.
  • Taxonomy, categorization, approval.
  • Interacts with digital asset management.
  • Pricing - often this comes from an ERP system and is not explicitly maintained in the commerce system.
• Author / Marketing Manager who maintains:
  • Marketing content for all channels.
  • Promotions.
  • Vouchers.
  • Campaigns.
• Surfer / Shopper who:
  • Views your product information.
  • Places items into the shopping cart.
  • Checks out their orders.
  • Expect order fulfillment.

Single-sign-on (SSO) is provided, so that authors are known in both systems without having to login twice.

Product data is maintained in hybris and can be made available in AEM.

Actual product information imported from hybris is held in the CRX repository under:

    /etc/commerce/products

The following properties indicate the link with hybris:

• commerceProvider
• cq:hybrisCatalogId
• cq:hybrisProductID

This data is synchronized as necessary.

For appropriate products information about variants can also be held. For example, for items of clothing the different colors available are held as variants:

Some of the product data that is maintained in hybris needs to be available in AEM. As the data can be very dynamic (new products, price changes, special offers, etc) a periodic synchronization is used together with a data feed of changes.

The eCommerce search API is fully implemented in the hybris solution, so you can use the eCommerce search component that is provided out-of-the-box:

hybris promotions cover everything that influences the shopping cart and is related to pricing. Promotion specific marketing content (such as banners, etc) is not part of the hybris promotion.

Promotions are not usually maintained by product information managers, but by marketing managers. The promotions are also integrated into the Campaign Management.

When a shopper registers, the account details need to be synchronized between AEM and hybris. Sensitive data is held independently, but profiles are shared:

hybris uses the context (essentially the shopper information) to determine the price on the hybris side then provide the correct information back to AEM.

Payment details, including credit card information, is managed by hybis. AEM forwards such transactional information to hybris (from where it is then forwarded to a payment processing service).

Payment Card Industry (PCI) complicance can be achieved.

Order fulfillment and tracking is managed by hybris. Information can be displayed by AEM.

hybris supports product content in multiple languages, this can be used by AEM.

When requesting data from hybris, the integration framework retrieves the language from the current tree (for example, en_US for pages under /content/geometrixx-outdoors/en_US).

For a multi-lingual store, you can import your catalog in each language tree individually (or copy it by means of MSM).

The product catalog sections provide you with, for example:

• an introduction (image and/or text) to the category; this can also be used for banners and teasers to promote special offers
  
• links to the individual products in that category
• links to the other categories

A AEM page (for example, using the Commerce Product template) can provide:

• general product information; text and images
  
• pricing

And allow the shopper to select:

• color and size variants
• quantity
  
• add to basket

The shopping cart provides:

• an overview of items selected
• links to the individual product pages
• updates to quantity
• removal of the item

Hybris stores the cart in a session so items are lost across log-in/log-out.

Price changes are reflected in both systems as they occur.

Often sign-up is required for the shopper to have access to the shopping cart. This requires registration so that a customer-specific account can be created.

After sign-up the shopper must login with their account so that their actions can be tracked and their orders fulfilled.

The hybris console is used for managing your product information; see the hybris documentation for more information.

The local instance included in the demonstration packages can be accessed using:

    https://localhost:9002/hmc/hybris

Login is required, the default details are:

• Account name:
  admin
• Password:
  nimda

The hybris package comes with a catalog importer for setting up the initial page structure.

This is available from:

    http://localhost:4502/etc/importers/hybris.html

The following information has to be provided:

• Base store
  The identifier of the base store configured in hybris.
• Catalog
  The identifier of the catalog to import.
• Root path
  The path where the catalog should be imported into.

The integration framework includes an integration layer with an API. This allows you to:

• plug in an eCommerce system and pull product data into AEM
• build AEM components for commerce capabilities independent of the specific eCommerce engine

A number of out-of-the-box AEM components are provided to use the integration layer. Currently these are:

• a product display component
• a shopping cart
• check-out

For search an integration hook is provided that allows you to use the AEM search, the search of the eCommerce system, a third party search (like Search&Promote) or a combination thereof.

The eCommerce framework can be used with any eCommerce solution, the engine being used needs to be identifiable by AEM:

• eCommerce Engines are OSGi services supporting the CommerceService interface
  • Engines can be distinguished by a commerceProvider service property
• AEM supports Resource.adaptTo() for CommerceService and Product
  • The adaptTo implementation looks for a cq:commerceProvider property in the resource's hierarchy:
    • If found, the value is used to filter the commerce service lookup.
    • If not found, the highest-ranked commerce service is used.
  • A cq:Commerce mixin is used so the cq:commerceProvider can be added to strongly-typed resources.
• The cq:commerceProvider property is also used to reference the appropriate commerce factory definition.
  • For example, a cq:commerceProvider property with the value hybris will correlate to the OSGi configuration for Day CQ Commerce Factory for Hybris (com.adobe.cq.commerce.hybris.impl.HybrisServiceFactory) - where the parameter commerceProvider also has the value hybris.
    
  • Here further properties, such as Catalog version can be configured (when appropriate and available).
    

See the following in the example below:

hybris uses a user session to store information such as the customer's shopping cart. The session id is returned from hybris in a JSESSIONID cookie that needs to be sent on subsequent requests to hybris. To avoid storing the session id in the repository it is encoded in another cookie that is stored in the shopper's browser. The following steps are performed:

• On the first request no cookie is set on the shopper's request; so a request is sent to the hybris instance to create a session.
• The session cookies are extracted from the response, encoded in a new cookie (for example, hybris-session-rest) and set on the response to the shopper. The encoding in a new cookie is required, because the original cookie is only valid for a certain path and would otherwise not be sent back from the browser in subsequent requests. The path information must also be added to the cookie's value.
• On subsequent requests, the cookies are decoded from the hybris-session-<xxx> cookies and set on the HTTP client that is used to request data from hybris.

• This session "owns" the shopping cart
  • performs add/remove/etc
  • performs the various calculations on the cart;
    commerceSession.getProductPrice(Product product)
• Owns the storage location for the order data
  CommerceSession.getUserContext()
• Also owns the payment processing connection
• Also owns the fulfillment connection

Product data that is maintained in hybris needs to be available in AEM. The following mechanism has been implemented:

• An initial load of IDs is provided by hybris as a feed. There can be updates to this feed.
• hybris will supply update information via a feed (which AEM polls).
• When AEM is using product data it will send requests back to hybris for the current data (conditional get request using last modified date).
• On hybris it is possible to specify feed contents in a declarative way.
• Mapping the feed structure to the AEM content model happens in the feed adapter on the AEM side.

• The importer (b) is used for the initial setup of the page tree structure in AEM for catalogs.
• Catalog changes in hybris are indicated to AEM via a feed, these then propagate to AEM (b)
  • Product added/deleted/changed with respect to catalog version.
  • Product approved.
• The hybris connector provides a polling importer ("hybris" scheme"), which can be configured to import changes into AEM at a specified interval (for example, every 24 hours where the interval is specified in seconds):
  • http://localhost:4502/content/geometrixx-outdoors/en_US/jcr:content.json
    {
    * "jcr:mixinTypes": ["cq:PollConfig"],
    * "enabled": true,
    * "source": "hybris:outdoors",
    * "jcr:primaryType": "cq:PageContent",
    * "interval": 86400
    }
    
• The catalog configuration in AEM recognizes Staged and Online catalog versions.
  
• Syncing products between catalog versions will require a (de-)activation of the corresponding AEM page (a, c)
  • Adding a product to an Online catalog version requires activation of the product's page.
  • Removing a product requires deactivation.
• Activating a page in AEM (c) requires a check (b) and is only possible if
  • The product is in an Online catalog version for product pages.
    
  • The referenced products are available in an Online catalog version for other pages (e.g. campaign pages).
• Activated product pages need to access the product data's Online version (d).
  
• The AEM publish instance requires access to hybris for the retrieval of product and personalized data (d).

A single product can have multiple variations; for instance, it might vary by color and/or size. A product must define which properties drive variation; we term these variant axes.

However, not all properties are variant axes. Variations can also affect other properties; for example, the price might be dependant on size. These properties cannot be selected by the shopper and therefore are not considered variant axes.

Each product and/or variant is represented by a resource, and therefore maps 1:1 to a repository node. It is a corollary that a specific product and/or variant can be uniquely identified by its path.

The product/variant resource does not always hold the actual product dataIt might be a representation of data actually held on another system (such as hybris). For example, product descriptions, pricing, etc, are not stored in AEM, but retrieved in real-time from the eCommerce engine.

Any product resource can be represented by a Product API. Most calls in the product API are variation specific (although variations might inherit shared values from an ancestor), but there are also calls which list the set of variations (getVariantAxes(), getVariants(), etc.).

In general:

• product data is located under /etc
  
• and product references under /content.

There must be a 1:1 map between product variations and product data nodes.

Product references must also have a node for each variation presented - but there is no requirement to present all variations.  For instance, if a product has S, M, L variations, the product data might be:

While a "Big and Tall" catalog might have only:

Finally, there is no requirement to use product data.  You can place all product data under the references in the catalog; but then you cannot really have multiple catalogs without duplicating all the product data.

API

• General Storage Mechanism
  • Product nodes are nt:unstructured.
  • A product node can be either:
    • A reference, with the product data stored elsewhere:
      • Product references contain a productData property, which points to the product data (typically under /etc/commerce/products).
      • The product data is hierarchical; product attributes are inherited from a product data node's ancestors.
      • Product references can also contain local properties, which override those specified in their product data.
    • A product itself:
      • Without a productData property.
      • A product node which holds all properties locally (and does not contain a productData property) inherits product attributes directly from its own ancestors.
• AEM-native Product Structure
  • Each variant must have its own leaf node.
  • The product interface represents both products and variants, but the related repository node is specific about which it is.
  • The product node describes the product attributes and variant axes.

Components

• The shopping cart is owned by the CommerceSession:
  • The CommerceSession performs add/remove/etc.
  • The CommerceSession also performs the various calculations on the cart.
• While not directly cart-related, the CommerceSession must also provide catalog pricing information (since it owns pricing)
  • Pricing might have several modifiers:
    • Quantity discounts.
    • Different currencies.
    • VAT-liable and VAT-free.
  • The modifiers are completely open-ended with the following interface:
    • int CommerceSession.getQuantityBreakpoints(Product product)
    • String CommerceSession.getProductPrice(Product product)

Storage

• Storage
  • In the hybris case, the hybris server owns the cart.
  • In the AEM-native case carts of are stored in the ClientContext

Personalization

• Personalization should always be driven through the ClientContext.
• A ClientContext /version/ of the cart is created in all cases:
  • Products should be added by using the CommerceSession.addCartEntry() method.
• The following illustrates an example of cart information in the ClientContext cart:

Cart and Order Data

The CommerceSession owns the three elements:

1. Cart contents
2. Pricing
3. The order details

Shipping Calculations

• Order forms often need to present multiple shipping options (and prices).
• The prices might be based on items and details of the order, such as weight and/or delivery address.
• The CommerceSession has access to all the dependencies, so it can be treated in a similar manner as product pricing:
  • The CommerceSession owns shipping pricing.
  • Can retrieve/update delivery details by using updateOrder(Map<String, Object> delta)

Payment Processing

• The CommerceSession also owns the payment processing connection.
• Implementors need to add specific calls (to their chosen payment processing service) to the CommerceSession implementation.

Order Fulfillment

• The CommerceSession also owns the fulfillment connection.
• Implementors will need to add specific calls (to their chosen payment processing service) to the CommerceSession implementation.
  

Following the standard service API model, the eCommerce project provides a set of search-related APIs that can be implemented by individual commerce engines.

The eCommerce project contains a default search component, located in:

    /libs/commerce/components/search

This makes use of the search API to query the selected commerce engine (see eCommerce Engine Selection):

There are several generic / helper classes provided by the core project:

1. CommerceQuery
   Is used to describe a search query (contains information about the query text, current page, page size, sort and selected facets). All eCommerce services that implement the search API will receive instances of this class in order to perform their search. A CommerceQuery can be instantiated from a request object (HttpServletRequest).
2. FacetParamHelper
   Is a utility class that provides one static method - toParams - that is used for generating GET parameter strings from a list of facets and one toggled value. This is useful on the UI side, where you need to display a hyperlink for each value of each facet, such that when the user clicks on the hyperlink the respective value is toggled (i.e. if it was selected it is removed from the query, otherwise added). This takes care of all the logic of handling multiple/single-valued facets, overriding values, etc.

The entry point for the search API is the CommerceService#search method which returns a CommerceResult object. See the API Documentation for more information on this topic.

Integration is provided between AEM and various eCommerce systems. This requires a strategy for synchronizing shoppers between the various systems so that AEM-specific code only has to know about AEM and vice-versa:

• Authentication
  AEM is presumed to be the only web front-end and therefore performs all authentication.
• Slave Accounts
  AEM creates a slave account in hybris for each shopper.  The username of the slave account is the same as the AEM username. A cryptographically-random password is auto-generated and stored (encrypted) in AEM.
  

A AEM front-end can be positioned in front of an existing hybris implementation. Also a hybris engine can be added to an existing AEM installation. To do this, the systems must be able to gracefully handle existing users in either system:

• AEM -> hybris
  • When logging in to hybris, if the AEM user does not already exist:
    
    • create a new hybris user with a cryptographically random password
    • store the hybris username in the user directory of the AEM user
      
  • See: com.adobe.cq.commerce.hybris.impl.HybrisSessionImpl#login()
• hybris -> AEM
  • When logging in to AEM, if the system recognizes the user:
    
    • attempt to log in to hybris with supplied username/pwd
    • if successful, create the new user in AEM with the same password (AEM-specific salt will result in AEM-specific hash)
  • The above algorithm is implemented in a Sling AuthenticationInfoPostProcessor
    • See: com.adobe.cq.commerce.hybris.impl.user.LazyUserImporter.java

To build upon existing functionality your custom import handler:

• has to implement the ImportHandler interface
  
• can extend the DefaultImportHandler
  

For your custom handler to be recognized by the importer, it must specify the service.ranking property with a value higher than 0; for example:

The eCommerce API is provided by the packages:

    com.adobe.cq.commerce.*

See the API documentation for further information.

Importing a large number of products (usually more than 100,000) from an eCommerce system (PIM) can slow down the authoring instance if the products have associated assets (eg product images). This is due to the fact that the post-processing of these assets is CPU and memory intensive.

There are various strategies you can choose to work around this:

• Offload asset post processing to a dedicated instance
• Only import product data

This scenario involves setting up two author instances:

1. Master author instance that imports product data from PIM, on which post-processing for the asset paths is disabled.
2. Dedicated DAM author instance that imports and post-processes product assets from the PIM, and replicates these back to the master author instance for use.

For cases when products do not contain assets (images) to be imported, you can import the product data without being affected by asset post-processing.