Migrate Your Accelerator-based Storefront to Project Spartacus
18 min read
migrate to a stateless high-performance architecture and now wonder how to actually
prepare for migration. In this article we will discuss an approach
suitable for small storefronts, but with a process that can also help larger migrations, where a full
re-implementation is recommended.
Table of Contents
To Migrate or Not?
Although the recommendation is to use the move to Spartacus as an opportunity to start fresh and rethink your storefront experience, you may have requirements to migrate to Spartacus and maintain the same experience. Depending on the number and method of customizing your accelerator-based storefront, you made find trying to migrate your existing experience over to Spartacus to be something simple or difficult. If you're unsure, you can use the steps below to go through an exercise to identify the number of changes without necessarily spending the time to implement. This can give you an idea of how much work may be required to migrate vs. starting with a greenfield approach.
As mentioned in "Getting started with SAP Commerce Cloud Project Spartacus" you can run your Accelerator and Spartacus storefronts at the same time to reduce risk, though it is recommended to not do this for a prolonged period. Maintaining two storefronts on two technology stacks can make development and testing quite difficult, not to mention you may be giving your customers an inconsistent user experience depending on which storefront page they are hitting.
It's recommended that you start your migration to a Spartacus storefront after upgrading to SAP Commerce 1905 or later, as the way Omni Commerce Connect (OCC) application programming interfaces (APIs) are installed has been simplified (they are now available as extensions instead of AddOns).
To get started you will also need the following:
- Review the Release Notes and Roadmap for Spartacus to ensure you are aware of which features have parity, which may have changed and which may be missing
- Upgraded your existing storefront to use at least SAP Commerce 1905
- Any existing OCC Addons have been converted into regular extensions (if using SAP Commerce 2005 or later)
- You have gone through the steps of "Build and Deploy Your First SAP Commerce Cloud Project". You may also want to review the content covered in Installing SAP Commerce Cloud for use with Spartacus, and ensure you have configured and performed the Spartacus project setup
The front-end team will build the storefront User Interface composed of layout and Angular Modules. The core skills of the developers will be:
See Getting started with SAP Commerce Cloud Project Spartacus for a complete list of front-end technologies that your team will need to get acquainted with, before embarking on a migration or re-implementation.
The back-end team will build the OCC APIs needed by the front-end team. The core developer skills needed are:
- SAP Commerce
Anatomy of a Spartacus-based Storefront
Before you begin your migration, you should be familiar with how a Spartacus storefront works. Start by visiting the Spartacus Storefront Documentation and taking a look at the Modules and Components directory. It will look like this:
Navigate the Modules and Components and get acquainted with the functionality offered by Spartacus. Pay special attention at Modules that provide a default <CmsConfig> which define the Mapping between standard CMS Components and Spartacus Components. In the example below, the BannerComponent provides mappings to SimpleResponsiveBannerComponent, BannerComponent and SimpleBannerComponent.
To see the which API endpoints are available in your local installation, navigate to the OCC Swagger documentation. You may need to install additional extensions if a given endpoint is missing.
|2005 and above|
|1905 and below|
Accelerator-based Storefront vs Spartacus-based Storefront
You might be familiar with the standard Spring-MVC based accelerator on the left side of the picture below, but look carefully to the description of the Spartacus storefront on the right to understand the key differences.
In the traditional storefront, the browser makes requests to the server which retrieve the page structure and executes controllers, facades and services to process and retrieve the information needed to render the view.
Most of the state is kept on the server-side.
In the headless storefront the front-end is loaded on the browser, and the page structure and layout is retrieved from the server (unless it has a static layout). The Spartacus Components (see Modules and Components above) are used to build the page on the client side, and they execute OCC Calls to the server (see OCC APIs above) to retrieve data needed for rendering. The initial page might, however, be built initially on the Server (using a technology known as Server Side Rendering - SSR), for performance and SEO purposes.
State is kept on the Client side.
During the migration, you will break down the existing accelerator Controller functionality into individual Spartacus Angular Components (also including the view/template logic) and OCC APIs, as indicated by the dotted lines. Be aware in some cases it might be necessary to also modify existing underlying Facades and Services.
Changes to the Content Catalog will also be required, the Spartacus documentation gives a good overview of the differences between the accelerator and Spartacus sample data.
Finally, you can analyze a sample call for the Product Details Page with the help of Chrome Developer Tools, to see how everything comes together. Use the Network Tab to see the requests generated by Spartacus.
Going through the calls above in more detail, using the Swagger API documentation as reference, you can see:
Requests the product details page including all WCMS Slots and Components.
Using the Component list in the response, Spartacus will use the CMSConfig mappings (see BannerModule example above) and will instantiate an Angular Component for each CMS Component and build the page using the structure provided by the slots, on the customer's browser.
|/sockjs-node/info||info?t=1597322562030||Only used during development, this socket is used to update the web app when the backend rebuilds|
Returns details of a single product according to the product code 300938
|/occ/v2/electronics-spa/cms/components||components?fields=DEFAULT&productCode=300938&curre…nk%2CBlankVideotapesCategoryLink&lang=en&curr=USD||Requests a list of the provided CMS components||
|/occ/v2/electronics-spa/languages||languages?lang=en&curr=USD||Gets a list of available languages||
|/occ/v2/electronics-spa/currencies||currencies?lang=en&curr=USD||Gets a list of available currencies||
|/occ/v2/electronics-spa/cms/components||components?fields=DEFAULT&productCode=300938&curre…ink%2CFacebookLink%2CTwitterLink&lang=en&curr=USD||Requests additional CMS components||
|/occ/v2/electronics-spa/users/anonymous/consenttemplates||consenttemplates?lang=en&curr=USD||Fetches the list of consents||
|/occ/v2/electronics-spa/cms/components||components?fields=DEFAULT&productCode=300938&curre…eviewsTabComponent%2CdeliveryTab&lang=en&curr=USD||Requests additional CMS components||
|/occ/v2/electronics-spa/products/300938||300938?fields=code,name,summary,price(formattedVal…nfiguratorType,configurable,tags&lang=en&curr=USD||Requests additional fields for product code 300938||
|Requests product references for product code 300938||
|/occ/v2/electronics-spa/products/300938||300938?fields=classifications&lang=en&curr=USD||Retrieves classifications for the product code 300938||
|/occ/v2/electronics-spa/products/300938/reviews||reviews?lang=en&curr=USD||Retrieves customer reviews for this product||
Using the Augury Chrome Plugin you can see the resulting component hierarchy after the page has been built in the browser.
Starting the Migration
Now that you understand how Spartacus works on a technical level, you are ready to proceed with the migration.
Step 1 - Make an Inventory of your CMS Components and Pages
It is important to make an inventory of the pages and components used in your current storefront, like in the
table below. For each page, list the controllers and custom CMS Components that are used,
and for each component, figure out which data it needs to display or process. Some of the
information needed might not be visible at first sight, such as dropdown boxes or pop-up windows.
You can filter requests to /pagescontentslotscomponents in SmartEdit while editing a given page in your existing storefront to retrieve the component details.
You may find it helpful to make screenshots of your storefront and annotate the components, like
Out-of-the-box Spartacus supports almost all responsive B2C CMS components, so you will only need to focus on your custom components, as well as those coming from third party addons or marketplace extensions not covered in the standard library. Group and classify them according to the functional area, using a component inventory like the one below. Be aware that unlike the Accelerator Page approach, everything needs to be a component in Spartacus, so you might need to componentize parts of an existing Jakarta Server Page (JSP) layout.
The following queries give you an overview of the Components, PageTemplates and Pages used in your storefront:
|ID||Page||Component||Implementation||Render in SSR||Nested||Data Needed||Notes||Component Screenshot|
|10.1||PDP||FinancingWidgetComponent||FinancingWidgetController||Yes||No||User, Cart, FinancingPreferences||Custom Layout|
|10.2||PDP||PersonalizedRecommendationsComponent||PersonalizedRecommendationsController||No||No||RecommendationList||Recommendation Engine could be queried directly|
|10.3||PLP||LastPurchases.jsp||JSP||Yes||No||Previous Orders||New Component needed|
On Page Controllers
In the standard accelerator, a PageController (based on AbstractPageController) prepares the context needed to render a page. In Spartacus most of this work is already performed by the framework, but it's a good idea to manually check for logic that might need to be moved to a custom OCC extension or an individual component.
Step 2 - Perform a GAP Analysis
For each component, identify if there is a corresponding OCC API that provides the needed data (and corresponding Injectable Service), otherwise describe the OCC Extensions that will be needed. Also, set a development priority (or importance) for each component.
Component GAP Analysis
|ID||Priority||Page||Component||Description||Data Needed||Existing OCC||Missing OCC|
|10.1||A||PDP||FinancingWidgetComponent||Calculates Product finance options||Customer, Cart, FinancingPreferences||Cart, Users||FinancingPreferences|
|10.2||B||PDP||PersonalizedRecommendationsComponent||Using Analytics recommends best rated products||RecommendationList||N/A||Recommendations|
|10.3||B||PLP||LastPurchases.jsp||Displays the last 3 online purchases||Previous Orders||Orders|
Step 3 - Start the API Implementation
Using an API First approach, create missing OCC Extensions and define the interfaces based on the semantics of existing OCC services. Start with empty (or mock) implementations as this will allow the front-end team to start work in parallel in the next step.
U se Swagger CodeGen to automatically generate the Typescript Angular client code needed in the front-end. Augment DTOs with necessary missing fields.
Step 4 - Implement the CMS Pages and Components
Create a base web content management system (WCMS) structure that duplicates your current storefront and launch your Spartacus application. Open your Console Tab in Chrome Developer Tools and you will see a warning for every CMS Component that does not have a corresponding Angular Component, there will also be a warning for the available CMS Slots.
Verify that this information matches your CMS Component Inventory
In the headless storefront the front-end is loaded on the browser, and the page structure and layout is retrieved from the server (unless it has a static layout). The Spartacus Components (see Modules and Components above) are used to build the page on the client side, and they execute OCC Calls to the server (see OCC APIs above) to retrieve data needed for rendering. The initial page might, however, be built initially on the Server (using a technology known as Server Side Rendering - SSR), for performance and SEO purposes. State is kept on the Client side.
Proceed to re-implement the new CMS components and Pages in Angular. Use the CMS
Component Schematic add-cms-component command to generate skeleton classes (see
also: Creating Pages and Components and Create a new page in
Spartacus ) and add your custom logic.
This article provided a more technical introduction to Spartacus and the techniques needed to migrate an existing accelerator storefront. A migration can involve a significant amount of re-engineering but there are tangible performance and maintenance benefits that make it worth it. Careful preparation is key to a successful migration.
If you have any questions, please do not hesitate to reach out to firstname.lastname@example.org . If you have technical questions as you develop on Spartacus we encourage you post your question to StackOverflow with the spartacus-storefront tag.