Concepts

The integration framework provides the mechanisms and components for:

• connection to an eCommerce engine
• 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, both AEM and the eCommerce engine concentrate on their own area of expertise. Information is transferred between the two in real time; for example:

• AEM can:
  • Request:
    • Product Information from the eCommerce engine.
  • Provide:
    • User views for product information, shopping cart and checkout.
    • Shopping cart and checkout information to the eCommerce engine.
    • Search Engine Optimization (SEO).
    • Community functionality.
    • Unstructured marketing interactions.
• eCommerce engine can:
  
  • Provide:
    • Product information from the database.
    • Product variant management.
    • Order management.
    • ERP (Enterprise Resource Planning).
      
    • Search within the product information.
  • Process:
    • 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 include:

• Product information
• Shopping cart
• Check-out
• My Account

Various search options are also available.

The integration framework provides the API, a range of components to illustrate functionality and several extensions to provide examples of connection methods:

The framework gives you access to functionality such as:

AEM eCommerce is implemented with an eCommerce engine:

• The eCommerce integration framework has been built to allow you to easily integrate an eCommerce engine with AEM. The purpose built eCommerce engine controls product data, shopping carts, checkout and order fulfillment, while AEM controls the data display and marketing campaigns.
  A reference site has already been implemented using hybris.

When importing data from a commerce engine into your AEM eCommerce site, a commerce provider is used to supply the importers with data. One commerce provider can support multiple importers.

A commerce provider is AEM code customized to either:

• interface to a back-end commerce engine
• implement a commerce system on top of the JCR repository

Two example commerce providers are currently available for AEM:

• one for geometrixx-hybris
• another for geometrixx-generic (JCR)

Though usually a project will need to develop their own, customized, commerce provider specific to their PIM and product data schema.

The ProductServicesManager maintains (through OSGi) a list of implementations of the ProductImporter and CatalogBlueprintImporter interfaces.  These are listed in the Importer/Commerce Provider dropdown field of the importer wizard (using the commerceProvider property as a name).

When a specific importer/commerce provider is available from the dropdown, any supplemental data it needs must be defined (depending on the importer type) in either:

• /apps/commerce/gui/content/catalogs/importblueprintswizard/importers
• /apps/commerce/gui/content/products/importproductswizard/importers

The folder under the appropriate importers folder must match the importer name; for example:

• .../importproductswizard/importers/geometrixx/.content.xml

The format of the source import file is defined by the importer.  Or the importer may establish a connection (e.g WebDAV or http) to the commerce engine.

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.

Though the actual location can depend on your implementation; for example, generic or with an eCommerce engine:

If the following two categories can be differentiated, then this allows you to make clear URLs with a meaningful structure (trees of cq:Page nodes) and therefore, very close to classical AEM content management):

• Structural categories
  The category tree defining what is a product; for example:
      /products/mens/shoes/sneakers
• Marketing categories
  All other categories a product can belong to; for example:
      /special-offers/christmas/shoes)

To portray and manage your product you will want to hold a range of information about them.

Product data can be:

• maintained directly in AEM (generic).
  
• maintained in the eCommerce engine and made available in AEM.
  Depending on the data type it is synchronized as necessary, or accessed directly; for example, highly volatile and critial data such as product prices are retrieved from the ecommerce engine (e.g. hybris) on every page request to ensure they are always up-to-date.

In either case, when the product data has been entered/imported into AEM it can be seen from the Products console. Here the card and list views of a product show information such as:

• the image
• the SKU code
• when last modified

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

The individual attributes held about each product may depend on the eCommerce engine being used and your AEM implementation. These are available (as appropriate) when viewing product pages and/or editing product information and can include:

• Image
  An image of the product.
  
• Title
  The product name.
  
• Description
  A textual description of the product.
  
• Tags
  Tags used to group related products.
• Default Asset Category
  A default category for assets.
  
• ERP Data
  Enterprise resource planning (ERP) information.
  
  • SKU
    Stock-keeping unit (SKU) information.
  • Color
    
  • Size
  • Price
    The unit price of the product.
• Summary
  A summary of the product features.
  
• Features
  Fuller details of the product features.

A selection of assets can be held for individual products. Commonly these include images and videos.

A catalog groups product data together for both ease of management and representation to the shopper. Often a catalog is structured according to attributes such as language, geographical area, brand, season, hobby, sport, amongst many others.

AEM supports product content in multiple languages. When requesting data, 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 for each language tree individually (or copy it by means of MSM).

As with languages, large multi-national companies can need to cater for multiple brands.

Tags can also be used to group products together into a catalog. These can be used for more dynamic catalogs such as seasonal offers.

Depending on your implementation, you can import the product data required for your base catalog into AEM from:

• a CSV file (for the generic implementation)
• the eCommerce engine

Further changes to the product data will be inevitable:

• for the generic implementation these can be managed with the product editor
• when using an eCommerce engine the changes must be synchronized
  

After the intial import, changes to your product data are inevitable.

When using an eCommerce engine the product data is maintained there and needs to be available in AEM. This product data needs to be synchronized when updates are made.  

This can depend on the type of data:

• A periodic synchronization is used together with a data feed of changes.
  In addition to this, you can select specific updates for an express update.
• Highly volatile data, such as price information, is retrieved from the commerce engine for each page request, to ensure that it is always up to date.

Importing a large catalog with a high number of products (usually more than 100,000) from an eCommerce engine (PIM) can impact the system due to the large number of nodes. It can also 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 these issues:

• Bucketing - to cater for the large number of nodes
  
• Offload asset post processing to a dedicated instance
• Only import product data
• Import Throttling and Batch Saves
• Performance Testing
• Performance - Miscellaneous

If a JCR node has a lot of direct child nodes (e.g. 1000 and more), buckets (phantom folders) are required to ensure that performance is not affected. These are generated according to an algorithm when importing.

These buckets take the form of phantom folders that are introduced to your catalog structure, but can be configured so they are not apparent in public URLs.

This scenario involves setting up two author instances:

1. Master author instance
   Imports product data from PIM, on which post-processing for the asset paths is disabled.
2. Dedicated DAM author instance
   Imports and post-processes product assets from the PIM, then 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.

Import throttling and batch saves are two general scaling mechanisms that can help when importing large volumes of data.

Performance testing must be taken into consideration on AEM eCommerce implementations:

• Author environment:
  Background (e.g. import) activity can occur at the same time as normal user activity (e.g. page editing) and even if front-end performance is (in general) given a higher priority, bad performance seen by online authors can lead to frustration capable of blocking a go-live decision.
  See also Test Scenarios - Author.
  
• Publication environment:
  Replication is a critical process to ensure that the content is published quickly and reliably. This can be impacted by how the author groups the content to be published.
  See also Test Scenarios - Publish.
  
• Front-end:
  The mixture of front-end and cache invalidations can potentially lead to performance surprises. Testing helps avoid these.

Please note that this performance testing requires knowledge and analysis of your target:

• Content volumes
  
  • Assets
  • Localized, I18ned products and SKUs
• User activity:
  • Bulk edition
  • Bulk publication
  • Intense search requests
• Background processes
  
  •  Imports
  • Synchronization updates (e.g. pricing)
• Maintenance requirements (backup, Tar PM optimization, datastore garbage collection, etc)

For all implementations the following points can be kept in mind:

• As product, stock-keeping units and categories can be numerous, try to use the least number of nodes possible to model the content.
  The more nodes you have, the more flexible your content is (e.g. parsys). However, everything is a trade-off and do you need individual flexibility (by default) when manipulating (for example) 30K products?
• Avoid duplication as much as you can (see localization), or when you do, think about how many nodes your duplication will lead to.
• Try to tag your content as much as you can in order to prepare the query optimization.
  For example:
      /content/products/france/fr/shoe/reebok/pump/46 SKU
  should have one tag per content level (i.e. country, language, category, brand, product). Searching for
      //element(*,my:Sku)[@country=’france’ and @language=’fr’
  and
      @category=’shoe’ and @brand=’reebok’ and @product=’pump’]
  will be drastically quicker than searching for
      /jcr:root/content/france/fr/shoe/reebok/pump/element(*,my:Sku)
• In your technical stack, plan very factorized content access model and services. This is a general best practice, but is even more crucial her, as you can, in optimization phases, add application caches for data that is read very often (and that you do not want to fill the bundle cache with).
  For example, attributes management is very frequently a good candidate for caching as it concerns data that is updated through products import.
• Consider use of proxy pages.

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

Product pages provide comprehensive information about individual products. Dynamic updates from are also reflected; for example, price changes that are registered on the eCommerce engine.

Product pages are AEM pages that use the Product component; for example, within the Commerce Product template:

The Product component provides:

• General product information; including text and images.
  
• Pricing; this is usually retrieved from the eCommerce engine every time the page is shown/refreshed.
  
• Product variant information; for example, color and size.

This information allows the shopper to select the following when adding an item to their basket:

• Color and size variants
• Quantity

These are AEM pages that provide primarily static information; for example, an introduction and overview with links to the underlying product pages.

The Product component can be added to any page with a parent page that delivers the required metadata (i.e. the paths to cartPage and cartObject). In the demonstration site, Geometrixx Outdoors, this is supplied by UserInfo.jsp.

The Product component can also be customized according to your individual requirements.

Proxy pages are used to simplify the structure of the repository and optimize storage for large catalogs.

Creating a catalog will use ten nodes per product as it provides individual components for each product that you can update and customise within AEM. This large number of nodes can become an issue if your catalog contains hundreds or even thousands of products. To avert any issues you can create your catalog using proxy pages.

Proxy pages use a two-node structure (cq:Page and jcr:content) that does not contain any of the actual product content. The content is generated, at request time, by referencing the product data and the template page.  

However, there is a trade-off. You will not be able to customize your product information within AEM, a standard template (defined for your site) will be used.

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

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

In AEM:

• A voucher is a page-based component that is created / edited with the Websites console.
  
• 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, 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).

Promotions are not usually maintained by product information managers, but by marketing managers:

• 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 the promotions are also integrated into the Campaign Management:

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

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

The exact mechanism can depend on the scenario:

1. The user accounts exists in both systems:
   
   1. No action required.
2. The user account exists only in AEM:
   1. User will be created in the eCommerce engine with same account ID and a random password which will be stored in AEM.
   2. The random password is necessary, as AEM tries to log into the eCommerce engine on the first call (for example, when a product page is requested and the eCommerce engine is referenced for the price). Because this happens after the AEM login, the password is not available.
3. The user account only exists in the eCommerce engine:
   1. The account will be created in AEM with same account ID and password.

When using an eCommerce engine, AEM only stores the account ID and password (optionally a user group). All other information is stored in the eCommerce engine.

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

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

Single-sign-on (SSO) is provided, so that authors are known in both AEM and the eCommerce system without having to login twice.

Transaction data from the eCommerce engine is combined with personal information about the shopper. AEM uses some of this data as profile data. A form's action in AEM writes information back to the eCommerce engine.

There is a page which allows you to easily manage your account informations. You can access it by clicking My Account at the top of a geometrixx page, or by navigating to  /content/geometrixx-outdoors/en/user/account.html.

Your site will need to store a selection of addresses; including delivery, billing and alternative addresses. This can be implemented using forms based on your default address format or you can use the Address Book component provided by AEM.

This Address Book component allows you to:

• edit addresses in the book
• select an address from the book for shipping address
• select an address from the book for billing address

You can choose which address you want as default. 

The address book component is reachable from the My Account page by clicking Address Book or by navigating to /content/geometrixx-outdoors/en/user/account/address-book.html.

You can click Add new address... to add a new address in your address book. It opens a form that you can fill out and then click Add address.

The Address Book is used when you checkout your cart:

Addresses are persisted below user_home/profile/addresses.
For example, for Alison Parker, it would be under  /home/users/geometrixx/aparker@geometrixx.info/profile/addresses

You can choose which address you want as default, this information is persisted in the shopper's profile rather than with the address. The profile property address.default is set with the path of the selected address for value.

The eCommerce engine uses the context (essentially the shopper information) to determine the price it is holding, then provide the correct information back to AEM.

When shopping the shopper will browse the product pages and select items to place them in their shopping cart. When they proceed to checkout an order can be placed.

An anonymous customer can:

• View products
• Add products to their cart
• Perform checkout to place their order

A registered customer can:

• Login to their account
• View products
• Add products to their cart
• Perform checkout to place their order
• View and track previous orders

The shopping cart provides:

• an overview of items selected
• links to the product pages for the selected items
  
• the capability to:
  • update the number/quantity of the individual items
  • remove individual items

The shopping cart is saved according to the engine being used:

• AEM generic stores the cart in a cookie.
  
• Certain eCommerce engines can store the cart in a session.

In either case, items stay in the cart (and can be restored) across log-in/log-out (but only on the same machine/browser). For example:

• browse as anonymous and add products to the cart
• sign in as Allison Parker - her cart is empty
• add products to her cart
• sign out - the cart will show the products for anonymous
  
• sign in again as Allison Parker - her products are restored

Prior to the checkout, price changes are reflected (in both systems) as they occur.

Depending on your implementation information about an order is held either in the eCommerce engine or AEM, this information is rendered by AEM.

A variety of information is stored, which can include:

• Order ID
  The reference number for the order.
  
• Placed
  The date the order was placed.
  
• Status
  The status of the order; for example, Shipped.
  
• Currency
  The currency of the order.
  
• Content Items
  A list of items ordered.
  
• Subtotal
  The total cost of the items ordered.
  
• Tax
  The amount of any taxes due on the order.
  
• Shipping
  Shipping costs.
  
• Total
  The total value of the order; items ordered, taxes and shpping.
  
• Billing Address
  The address to be which the invoice should be sent.
  
• Payment Token
  The payment method.
  
• Payment Status
  The status of the payment.
  
• Shipping Address
  The address to which the goods should be shipped.
  
• Shipping Method
  The method of shipping; for example, land, sea or air.
  
• Tracking Number
  Any tracking number used by the shipping company.
  
• Tracking Link
  The link used for tracking the order while being shipped.

When the order is held within AEM the Order console shows the following for each order:

• the number of items in the cart
  
• the total value of the order
  
• when the order was placed
• the status
  

After placing an order, shoppers will often return to:

• Check the status of their order
• Remove products from the order
• Add products to the order

After receiving the order delivery, shoppers may also want to view the history of orders made over a period of time.

Order fulfillment and tracking is usually managed by the eCommerce engine. Information can be displayed by AEM using the Order History component, which shows all relevant details, including the vouchers and promotions applied. For example:

Checkout is implemented with standard AEM forms. This allows the marketing manager to customize the experience with marketing content.

The eCommerce then manages the checkout process with input from the AEM forms.

Payment details, including credit card information, are often managed by the eCommerce engine. AEM forwards such transactional information to the engine (from where it is then forwarded to a payment processing service).

Payment Card Industry (PCI) complicance can be achieved.

The order is confirmed on screen and can be tracked with the order tracking.

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

When using an eCommerce engine, the eCommerce search API can be fully implemented in the eCommerce engine solution (e.g. hybris), so you can use the eCommerce search component that is provided out-of-the-box. The faceted search allows you to search either JCR and/or the engine: