This document introduces the key architecture aspects of SAP Commerce Accelerator. It is intended as a reference for developers, software architects, system architects, and consultants.
Commerce Accelerator combines a feature-rich web application with a collection of software components that fulfill many typical use cases that are common requirements on a vast number of SAP Commerce implementation projects. This document helps you understand the software as well as understand in more detail the features implemented by the software, how everything fits together, and how you can adapt the code or configure it to fulfill your project’s requirements.
This document begins with a brief guide about how to use the document. Following that is a look at the architecture of an Acceleratordriven deployment, which is presented to show a broad overview of the components involved. From there, you can pursue any topic, be it a guide to an extension, a guide to some specific functionality, and so on.
Using this Document
This section guides you about how to use this document.
Approaching the Documentation
There are two ways you can approach this documentation:
- You can deep-dive into one of the Accelerator extensions to find documentation related to the functionality and software components provided by that extension.
- You can read through specific topic area documentation, where functionality may cross the boundaries of multiple extensions.
The first use case tends to apply to developers who already have the code in front of them and want to understand part of it. The second use case applies to an architect or developer who wishes to understand the big picture of a more specific topic area such as how Advanced Personalization is handled in Accelerator or how Search and Navigation works.
Understanding Data Model Diagrams
Accelerator uses a flexible type system that lets extensions add additional attributes to existing types. During build time, model objects are generated and compiled from the type system definition, located in the items.xml file, and the result is the complete data model.
Accelerator requires a specific set of extensions out-of-the-box, but like the rest of SAP Commerce, it does not impose any limitations on further extensions being added that include data model changes.
Unless it is required to improve the clarity of the diagram, all the Accelerator data model diagrams only show the attributes and relationships of types added in the Accelerator extensions. You need to refer to other counterpart documentation to see a fuller picture of the data model. Where a type was extended, the UML stereotypes were used to identify at the class level in which extension the type was added, or at the attribute level which extension added the attribute.
The following diagram shows this:
The BaseStore class is declared in the SAP Commerce basecommerce extension. The <net>, <taxGroup>,<defaultCurrency>, and <defaultLanguage> attributes are all declared in the commerceservices extension.
For more information, see basecommerce Extension.
Multitier Architecture
There are many types of system and software components that can make up a SAP Commerce deployment, indeed there is probably not one typical SAP Commerce deployment. The numbers of servers and components completely differ depending on the implementation requirements. To give you an understanding of the kind of system and software components you typically work with on a project starting with Accelerator as a base, the following section describes how various types of components physically and logically fit together. You can find more details about each component in the counterpart sections of the documentation.
For more information, see the following:
- Storefront Web Application Deconstructed
- Spring Usage
- Business Processes and Eventing
- Data Importing
- WCMS Email and Process Engine Integration
- commercefacades Extension
The diagram below shows an example deployment setup of the Accelerator based implementation. The rest of this section provides more details about the deployment presented in the diagram.
Figure: Example deployment of the SAP Commerce Accelerator based system.
Web Server
It is common to use a web server such as Apache to store static assets such as images, CSS, and JavaScript files. This is typically done to ensure the application server resources are not troubled with serving assets that can be served from the web server with greater performance.
For more information, see the following:
- Running SAP Commerce
- http://httpd.apache.org/docs/2.2/install.html: Compiling and Installing Apache Server
- http://learn.iis.net/page.aspx/26/installing-and-configuring-iis-7/: Installing and Configuring IIS7
SAP Commerce Application Server Nodes
Although it is possible to install all the software components in SAP Commerce on a single run time, it is more desirable to set up a cluster of servers to separate the functions that are dedicated to serving real-time customer web requests from those that perform asynchronous processes or administration interfaces. This preference is driven by performance, fault-tolerance, and network security reasons.
For more information, see the following:
- Cluster
- Setting Up a Production System
- http://tomcat.apache.org/tomcat-7.0-doc/setup.html: Apache Tomcat Setup Guide
You can divide the software components that run inside the SAP Commerce run time into separate logical layers. There is a brief description and reference to further information for each layer.
Web Request Application Server Node
You can set up one or more application servers to service requests from the web. These could be just requests on the websites or requests from web services. The state is maintained using HTTP sessions. The requests are often proxied through a web server and often a session ID aware load balancer is installed to ensure that load is distributed evenly to all available application servers.
Presentation Layer
The presentation layer consists of following components:
- Servlet Components
- Filters
- Listeners
- Dispatcher Servlet
- Media Servlet
- Spring MVC
- Dispatcher Servlet
- Controllers
- Interceptors
- View
- JSP/JSTL
For more information, see the following:
- Storefront Web Application Deconstructed
- mediaweb Extension
- ServiceLayer
- items.xml
- ServiceLayer Architecture
ServiceLayer
The ServiceLayer API consist of following components:
- Facades
- Services
- Data Access Objects
Commerce Accelerator uses services and facades exposed in the commerceservices and commercefacades extensions. Both of these extensions contain implementations of commerce-related services and facades, which you can use in different clients that require access to some higher level commerce methods.
The Commerce Accelerator project also contains two additional extensions: acceleratorservices and acceleratorfacades. You can place all Accelerator-specific implementations of the service layer in one of these extensions.
Persistence Layer
The persistence layer is all out-of-the-box and requires very little work on the project side except describing/modifying types in the items.xml file.
Simple Request Interaction Diagram
The following interaction diagram shows how the application server components interoperate to service a client request:
Back Office Application Server Node
Back office functions including various administration interfaces can be separated onto different physical application servers. This can simplify security as administrative applications that should not be available across the Internet can simply be installed on a back office machine without Internet access. Back office processes tend to require different types of data to be cached, thus helping to improve cache performance. It can also be desirable to allow for a little downtime possibility on back office nodes, separating the back office process allows you to do this without having downtime on the storefront.
Administration Applications
The following applications can be used for the administration of your system:
- Management Console
- Administration Web
- Business and Administration Cockpits, for example:
- Administration Cockpit
- Product Cockpit
- WCMS Cockpit
- Report Cockpit
- Print Cockpit
- Customer Service Cockpit
For more information, see the following:
- End user documentation:
- Technical documentation:
ServiceLayer
The SAP Commerce Accelerator and SAP Commerce are based on the ServiceLayer API. The following technologies are used within the SAP Commerce Accelerator:
- Cron Jobs
- Tasks, Processes, and Actions
- Hot Folder Data Importer
- Services
- Data Access Objects
- SOLR Indexer
For more information, see the following:
- The cronjob Service
- The Task Service
- The SAP Commerce processengine
- The SAP Commerce processengine
- Data Importing
- commerceservices Extension
- ServiceLayer Architecture
- Search and Navigation
Persistence Layer
The persistence layer is all out-of-the-box and requires very little work on the project side except describing/modifying types in theitems.xml.
Diagram of Logical Organization of Software Components
The following diagram shows how the components are arranged into their logical tiers:
Solr Standalone
SAP Commerce packages Solr 5, which doesn’t support running Solr in Embedded mode. To assist projects in their development, a number of new Ant Tasks are available. For more information, see Search and Navigation Module and solrfacetsearch Extension.
Relational Database
SAP Commerce supports a wide range of RDBMS. For more information, see Third-Party Databases.
Other Components Not Covered
- Load Balancers
- VIPs
- Firewalls
- SFTP/FTP Servers
- Media Asset Management Systems
- ERP Systems
- Payment Service Providers
- CRM Systems
Integration Points To Consider
SAP Commerce Accelerator provides a great deal of functionality straight out-of-the-box, but projects need to consider additional integration points to other external systems. The following deployment diagram identifies integration points to some more common third-party systems that may need additional development effort. This list is not exhaustive, but it is a list of fairly common integration points in a B2C implementation.
ERP as a Product Data Source
If SAP Commerce PCM is not going to be the master for product information, the project’s customer usually has one or more existing Enterprise Resource Planning (ERP) systems in place that contain the master product and pricing data. The project customer may also have an existing Enterprise Application Integration (EAI) tool that is used to integrate the company’s various systems. It may be the customer doesn’t have anything as sophisticated as an ERP – regardless, the point is that a separate system contains the product/pricing master data and this data needs to be integrated with SAP Commerce.
For more information, see Data Importing
The yacceleratorcore extension provides a Hot Folder Data Import feature based on Spring integration. Out-of-the-box, you can drop CSV files into a hot folder location and you can configure the application to load these files in a batch and update SAP Commerce. If the implementation project just requires additional files and attributes and the CSV format is fine, then the level of effort should be quite low. If a project is lucky enough to be able to dictate the file format, then the level of effort is reduced even more.
If updates have to arrive in a different format, then you need to adapt the Data Import feature to work with differing formats by integrating a different ImpexTransformer. Furthermore, if the format is not delivered as a file, then you need to adapt theServiceActivator to handle the new inbound format, such as ESB Integration, a JMS Message, or a WebService request. In the later case, the software provided by the Hot Folder Data Import feature is little more than a reference of how to use Spring Integration to integrate external data sources into SAP Commerce.
Warehouse
Most websites that sell physical products need some direct interaction with a Warehouse Management System (WMS) or a Stock Control System if Cart & Checkout is to be used to control the full fulfillment process.
The template yacceleratorfulfilmentprocess extension provides various stubs where interfaces to a WMS could be implemented for a project. Out-of-the-box, a Warehouse Mock simply pushes the order through the fulfillment process. Effectively, a project needs to replace the Mock with the integration code that interfaces with the WMS. The yacceleratorfulfilmentprocess extension is built using the SAP Commerce Process Engine, so you can adapt it to meet project-specific fulfillment workflows. Generally, interfacing with warehouse systems incurs quite lengthy testing to ensure all the various order process permutations get sufficient coverage, so this would usually require a high level of effort.
For more information, see the following:
Payment Service Provider
The yacceleratorstorefront extension takes payment card information and expects a third-party Payment Service Provider (PSP) to support a subscription saved-card based service primarily to ensure that customers sensitive card information, like the number and CVV, do not need to be stored in the SAP Commerce database. The integration with the PSP is a deep integration, in that the web application still receives the full card details and then, in the same request, passes them on to the PSP.
By default, a Mock PSP is enabled, but Accelerator also offers the cybersource extension, which adds a CardPaymentServiceimplementation for cybersource. Accelerator has been tested with cybersource. Using cybersource as the payment service provider is mostly a configuration effort with CyberSource and therefore has a low effort impact. If a project has to integrate a different payment service provider, then this needs a new CardPaymentService implementation. This entails at least a medium level of effort.NoteThe CyberSource extension has been removed from the SAP Commerce distribution.
Two different payment flows are present out-of-the-box:
- hosted page: where the user is being redirected to a 3rd party page to enter credit card information
- order post: where a credit card form is rendered in the Accelerator and posted directly to the 3rd party
These two solutions have their implementation in cybersource (HOP and SOP) and are supported by Accelerator out-of-the-box.
Other payment providers support the same type of flow and implementing another payment provider entails at least a medium level of effort.
For more information, see the following:
Fraud Service Provider
SAP Commerce Accelerator ships with a score-based extensible Fraud Detection system that allows you to do real-time checks against certain aspects of an order or a customer. Essentially, the checks look for certain symptoms and rank the results with a score. If the result of all the checks is a score that exceeds a tolerance threshold, the order is put on hold.
If a project requires additional fraud checks to be carried out by an external fraud service provider, typically due to a requirement for accessing external information like blacklisted cards or a credit history, then it is possible to plug such a provider directly into the fulfilmentprocess by implementing a new FraudServiceProvider. The new provider can either replace the standard SAP Commerce provider or be added as a separate fraud check step.
It is also possible to extend the existing symptom detection logic in the SAP Commerce Fraud Service and add additional rules.
This integration tends to constitute a low level of effort to add a few extra rules, pushing to medium-high to integrate a whole new external fraud provider.
For more information, see Fraud Detection.
Media Server
SAP Commerce provides digital asset management features. This is not demonstrated with SAP Commerce Accelerator as it requires installation of third-party software that complicates the basic developer-ready install, but the system is fully compatible. You can integrate it directly into the cockpits to pull media directly from the platform as well as supporting the creation of automated jobs to pull updated media without any manual intervention. It should be deemed low to medium effort to get this module running.
Content Delivery Networks (CDN) support for images is not explicit, however you can integrate such support into the facade layer by effectively replacing the standard ImageConverter. Out-of-the-box, this uses a Media as the source to create the prototypeImageData object. However, you can replace it with one that can generate ImageData objects using another source, for example something as simple as a naming convention. This would be low to medium effort.
Analytics
It is common to include analytics on a web site to figure out how your customers are using the site and what pages are popular and unpopular. Typically this involves adding the necessary data you wish to track in the page view and including some JavaScript on each page.
Out-of-the-box the yacceleratorstorefront extension includes integration of Google Analytics via the analytics.tag file. Further implementations can be added through this file or in an AddOn.
For more information, see the following:
Site Map
You may want to generate a Search Engine Site Map to place on your website web server. A CronJob is provided that will generate Google-compliant Site Map XMLs and make them available in the standard sitemap.xml file.
For more information, see Sitemap Configuration.
- Wikipedia on Sitemaps
B2B Commerce Module
The SAP Commerce B2B Commerce Module allows you to leverage the SAP Commerce B2C features in a B2B context. The B2B module is now delivered as a set of AddOns to the base Accelerator.
For more information, see the following:
The B2B Commerce Module provides an intuitive way to interact with client companies, to assign different prices, allow access to different catalogs, promote special quote negotiations, and extend different credit limits. Additionally, you provide the customers with the tools to manage their own organizations, employees, and company hierarchy. Therefore, to set up a new client, you only need to create a new organization and a new customer in that organization with administration roles. From that point forward the new customer with the administration role can expand, configure, oversee, and maintain the organization.
B2B Organizations
A client organization is set up to be hierarchical where each node is called a unit. A unit may represent a subdivision such as a department. An individual customer exists as a member of a unit within this hierarchy. Many rules and criteria are derived from the hierarchy, for example the transaction approvers associated with a customer, what credit limits apply, or what cost centers customers may access.
To demonstrate organization setups that clients might have, the powertoolsstore extension in Accelerator provides two fictitious client organizations. Please see the diagram below for more details.
Figure: Reference B2B store, shipped with SAP Commerce Accelerator.
The reference B2B store available in the Accelerator package has four account managers for various units. The diagram above illustrates the interaction between account managers, the customers, customers in different locations in the company hierarchy, the various purchasing permissions, and the responsibilities and purview of customers with various roles.
B2B Credit Limits
Within the reference organization, you may find a credit limit of $40 000 a month and a quote negotiation threshold of $10 000. You may impose a credit limit on a company, after which point orders do not go through without the explicit approval of the designated account manager. Additionally, with Accelerator, there is a quote negotiation threshold set up, which permits orders with higher totals to be eligible for price negotiation with an account manager.
Roles and Visibility
There are four roles with different privileges that you can grant to customers: Admin, Manager, Approver and Customer. You give roles to customers by adding them to the following usergroups: b2badmingroup, b2bmanagergroup, b2bapprovergroup andb2bcustomergroup. Administrators have many configuration options for their organization. They can designate budgets not to be exceeded, determine different purchasing rules for different staff members, designate approvers, and mandate delivery addresses. Members of b2bcustomergroup can make purchases and b2bapprovalgroup members can approve orders, other factors not withstanding.
The unit a customer is a member of in the hierarchy determines his visibility within the organization. Members, even administrators, can only access entities associated with their parent units as well those associated with any of its subunits. In our diagram, a customer Admin A presides over an organization of six units or departments. Admin B is set up further down in the hierarchy where Admin B can manage the immediate unit, as well as all of its subunits, but Admin B may not access entities, that is customers, cost centers, and permissions above Admin B‘s parent unit.
Cost Centers and Budgets
As customers place purchases against the company account, they must bill them to specific cost centers. Per visibility, they have access to cost centers assigned to their unit, and the cost centers in their branch. Cost centers also dictate the delivery address they may choose. A budget, set up by an administrator, is associated with each cost center. Once purchases against the cost centers exceed the budget, no further purchases are allowed without explicit permission.
Order Permissions and Order Approval Process
There are three checks that are verified before an order is placed. This is the stock configuration of the b2bapprovalprocessextension. Please refer to documentation about b2bapprovalprocess extension to learn how to configure and create new permissions and approval processes to suit your specific needs. The three implemented permissions are Order Threshold Permission, Order Threshold Timespan Permission, and Budget Exceeded Permissions.
For more information, see b2bapprovalprocess Extension.
An administrator creates instances of the permissions such as Order Threshold Permission with varying threshold amounts, for example $500, $5000, and so on. These permissions are then either directly assigned to the customers or added to a permission group and the permission group is assigned to a customer.
Upon initiating an order, the approval processes evaluates the order against the customer’s permissions. The order gets placed if the customer possesses all three required permissions for that order. If the customer permissions are not sufficient, the b2bapprovalprocess approval strategy searches for approvers assigned directly to the purchaser, then searches the parent unit, and then up the organization units until it finds an approver who possesses the missing permissions to place that order. Once an approver is found, it appears in the approvers Order Approval Dashboard where the approver may add a comment and approve or reject the order.
Google Local Shopping Export
SAP Commerce Accelerator supports exporting product data, prices, and store locations to Google Shopping / Local, so that customers can find products in their local stores via the Google search.
The process of exporting data to Google Local Shopping is split into two separate parts. The first part generates the data file and the second part uploads the data files to the Google servers. Both processes are triggered by a CronJob. The CronJob initiates a spring integration pipeline, which actually does the work.
For more information, see the following:
- Getting started with Content API for Shopping
- Creating an Account with Google Local Shopping
Generating Export Data
The DataExportCronJob initiates the process of generating the data files. It executes the DefaultExportDataJobPerformablejob and is configured with the following parameters:
| Parameter | Description |
|---|---|
| baseStore | The base store to export products and stores from. |
| cmsSite | The CMS site used to build links to the online products. |
| language | The language for the data to export. |
| currency | The currency for the product prices to export. |
| user | The user to run the export as, which controls the available products, prices, taxes, and so on. |
| thirdPartyHost | The upload location for the generated files. |
| thirdPartyUsername | The username of the third party account. |
| thirdPartyPassword | The password of the third party account. |
| dataGenerationPipeline | The name of the spring integration pipeline that generates the data |
The default Spring integration pipelines for Google Local Shopping export are exportGooglePosPipeline andexportGoogleProductPipeline. The exportGooglePosPipeline exports all the stores in the selected base store. TheexportGoogleProductPipeline exports all the products in the selected base store. Google suggests the store export be generated at least monthly, and the product export be generated at least weekly. As these two different exports have to be triggered by different cron jobs, it is straight forward to configure them with different schedules.
The generated files are written to the local file system, if SAP Commerce is running in a cluster, then the files are written to the node where the export cron job executes. The export folder location is looked up via the runtime configuration property<acceleratorservices.export.basefolder>, which defaults to ${HYBRIS_BIN_DIR}/ext-accelerator/acceleratorservices/export. The generated files are named to allow the upload process to identify the data export cron job that generated it.
Uploading Data
The data upload is initiated by a GenericCronJob executing the DefaultUploadDataJobPerformable. This triggers a Spring integration pipeline that looks for generated data files that need to be uploaded. The filename allows the export cron job to be identified and from that the upload configuration can be read. The file it uploaded to the thirdPartyHost using the thirdPartyUsername and the thirdPartyPassword.
Customizing the Export
The main aspect of the Google Local Shopping export that you need to customize is the conversion beans that convert the SAP Commerce items into the appropriate record format for export to Google:
| Bean | Converter Type | Source Type | Target Type |
|---|---|---|---|
| exportGooglePOSConverter | de.hybris.platform.acceleratorservices.dataexport.googlelocal.converter.PosConverter | PointOfServiceModel | Business |
| exportGoogleProductConverter | de.hybris.platform.acceleratorservices.dataexport.googlelocal.converter.ProductConverter | ProductModel | Product |
Store Locator
Store Locator is a functionality that helps consumers find stores in the proximity of a given postal code or city name. The StoreLocatorFacade is exposed in the commercefacades extension, and it uses services from basecommerce extension. Searching and returning results is based on PointOfService objects stored in the database.
For more information, see the following:
Customer Reviews
Customer reviews is a functionality that allows clients to add a review to a product. In the commercefacades extension, retrieved product data is filled with reviews that are fetched from database. All service layer functionality related to customer reviews is incustomerreview extension. Search restrictions that limit fetched reviews only to approved and belonging to customer user group is turned on by default and can be deactivated with the property key <customerreview.searchrestrictions.create>.
For more information, see the following:
