Introduction

This document discusses steps to migrate an Intershop storefront that is not yet based on the Responsive Starter Store (introduced with Intershop 7.6) to a storefront based on the Responsive Starter Store. These are manual migration steps and there cannot be an automated process for this.

While the Guide - 7.6 Migration to Responsive Starter Store describes the migration steps that are necessary to migrate an Intershop 7.5 PrimeTech based storefront to the Responsive Starter Store in a more specific way, this guide is intended to describe the more general steps, which are necessary to migrate to the Responsive Starter Store from a base that is - concerning the content model and the storefront functionality and source code - not as close as the Intershop 7.5 PrimeTech storefront.

Migration in the context of this document means, what needs to be done to get a Responsive Starter Store storefront running on top of an updated customer project that was migrated to a current Intershop version. This does not mean that the customer's customized storefront is fully migrated to a customized version of the Responsive Starter Store.

Steps

1. Back up the customized content.
   As for any such attempt a system backup is highly advised (e.g., "ant export").
2. Remove CMS content from the data base.
3. Start customizing the white-label store.

4. Remove the custom storefront cartridges / storefront content.

5. Add your custom cartridges.

6. Migrate the project data.

7. Remove all branding packages.

8. Initialize the storefront.

9. Migrate required parts of the project content model.

10. Migrate relevant parts of the exported CMS content.

11. Adapt the migrated content to the new Responsive Starter Store's styling and structure.

12. Migrate the storefront customizations.

Export CMS Content - Backup

Since it is not possible to migrate the CMS content of older or highly customized content models automatically to the content of the Responsive Starter Store, it is necessary to export the current content. So it can be at least partially migrated and re-imported later on.

For that reason:

1. Export all CMS content of all organizations, channels and applications, preferably as ZIP export.

   The exports can be done in the Intershop Commerce Management application. The ZIPs need to be downloaded from the server and saved for further processing.

   The content of these ZIP files will than be the base for manual transformations and might be partially re-imported into the new Responsive Starter Store content.

Remove CMS Content from the Database

The older CMS content is not compatible to the content model of the Responsive Starter Store. Thus it is best to completely remove the old content from the database. Use the white-label store content of the Responsive Starter Store and develop your content model from scratch. Parts of the older CMS content might be migrated and imported afterwards. For that we have the ImpEx files of the backup before.

The Intershop Commerce Management already provides procedures the can be used to completely delete the CMS content for a given domain.

set echo on
set verify on
define dn = &1
begin
    sp_deleteMarketingPAByDomain(domainid('&dn'));
    sp_deletePEPAByDomain(domainid('&dn'));
    sp_deletePageletsByDomain(domainid('&dn'));
end;
/
commit;
exit

The attached remove_content.sql can be used together with a command line script to remove all CMS content data from the database.

sqlplus USER/PASSWORD@ISSERVER.world @remove_content.sql inSPIRED-inTRONICS-b2c-responsive

After removing the old storefront content the storefront can later be reinitialized with the white-label store content of the Responsive Starter Store.

Set Up a Project Based on the Responsive Starter Store

With the introduction of the Responsive Starter Store there have been several changes on how to set up a customer project. This procedure is described in detail in the Recipe: Set Up Project based on the Responsive Starter Store. For migration across multiple versions it is probably best to:

1. Set up your project by starting with a clean Responsive Starter Store.

   Note

   It is necessary to follow the mentioned recipe to set up your project. While doing this one needs to remove the not needed parts of the Responsive Starter Store, e.g., the B2X cartridges if you are only interested in a B2C shop and especially for a migration project the demo initialization cartridges.

2. Adapt it to the customizations of your current project.

Revert the Application Type

One important step for a migration project is the adaption of the application type. Projects that are based on Intershop prior to version 7.6 usually use the storefront application type intershop.B2CWebShop while the Responsive Starter Store application type is intershop.B2CResponsive. For a migration scenario from an intershop.B2CWebShop storefront to the Responsive Starter Store storefront it is not feasible to use the application types of the Responsive Starter Store (intershop.B2CResponsive,intershop.SMBResponsive) defined in as_responsive. Instead, the application types (intershop.B2CWebShop, intershop.SMBWebShop) of the existing project need to be kept. There is no easy way to migrate the application types of existing application instances and its representation in the shared file system. It is much easier to:

1. Change the application type ID of the Responsive Starter Stores storefront application type definition.
   This is done in the apps.component file of the as_responsive cartridge.

   apps.component of as_responsive

   <components xmlns="http://www.intershop.de/component/2010">
   
       <!-- ************************************************************************************ -->
       <!-- *           Application Type "intershop.B2CResponsive"                             * -->
       <!-- ************************************************************************************ -->
   
       <instance name="intershop.B2CResponsive.Cartridges" with="CartridgeListProvider">
           <fulfill requirement="selectedCartridge" value="app_sf_responsive_b2c"/>
           <fulfill requirement="selectedCartridge" value="app_sf_responsive_cm"/>
           ...
           <fulfill requirement="subProvider" with="intershop.DemoCartridges" />
       </instance>
       <instance name="intershop.B2CResponsive" with="ApplicationType">
           <fulfill requirement="id" value="intershop.B2CResponsive"/>
           <fulfill requirement="urlIdentifier" value="b2c-responsive"/>
           <fulfill requirement="cartridgeListProvider" with="intershop.B2CResponsive.Cartridges"/>
           ...
       </instance>
       ...
   
       <!-- ************************************************************************************ -->
       <!-- *           Application Type "intershop.SMBResponsive"                             * -->
       <!-- ************************************************************************************ -->
   
       <instance name="intershop.SMBResponsive.Cartridges" with="CartridgeListProvider">
           <fulfill requirement="selectedCartridge" value="app_sf_responsive_smb"/>
           <fulfill requirement="selectedCartridge" value="app_sf_responsive_cm"/>
           ...
           <fulfill requirement="subProvider" with="intershop.DemoCartridges" />
       </instance>
       <instance name="intershop.SMBResponsive" with="ApplicationType">
           <fulfill requirement="id" value="intershop.SMBResponsive" />
           <fulfill requirement="urlIdentifier" value="smb-responsive" />
           <fulfill requirement="cartridgeListProvider" with="intershop.SMBResponsive.Cartridges" />
   		...
       </instance>
   	...
   </components>
   

   In the apps.component file the following changes would be necessary:

   original naming	changed naming
   B2CResponsive	B2CWebShop
   b2c-responsive	b2c-web-shop
   SMBResponsive	SMBWebShop
   smb-responsive	smb-web-shop

2. Additional application type definition files like apps-extension.component of as_responsive_b2b need to be changed too if they are used (in a B2B storefront).

   Please consider there might be additional files like this due to the customization of your project.

   changed apps.component to work with intershop.B2CWebShop or intershop.SMBWebShop

   <components xmlns="http://www.intershop.de/component/2010">
   
       <!-- ************************************************************************************ -->
       <!-- *           Application Type "intershop.B2CWebShop"                                * -->
       <!-- ************************************************************************************ -->
   
       <instance name="intershop.B2CWebShop.Cartridges" with="CartridgeListProvider">
           <fulfill requirement="selectedCartridge" value="app_sf_responsive_b2c"/>
           <fulfill requirement="selectedCartridge" value="app_sf_responsive_cm"/>
           ...
           <fulfill requirement="subProvider" with="intershop.DemoCartridges" />
       </instance>
       <instance name="intershop.B2CWebShop" with="ApplicationType">
           <fulfill requirement="id" value="intershop.B2CWebShop"/>
           <fulfill requirement="urlIdentifier" value="b2c-web-shop"/>
           <fulfill requirement="cartridgeListProvider" with="intershop.B2CWebShop.Cartridges"/>
           ...
       </instance>
       ...
   
       <!-- ************************************************************************************ -->
       <!-- *           Application Type "intershop.SMBWebShop"                                * -->
       <!-- ************************************************************************************ -->
   
       <instance name="intershop.SMBWebShop.Cartridges" with="CartridgeListProvider">
           <fulfill requirement="selectedCartridge" value="app_sf_responsive_smb"/>
           <fulfill requirement="selectedCartridge" value="app_sf_responsive_cm"/>
           ...
           <fulfill requirement="subProvider" with="intershop.DemoCartridges" />
       </instance>
       <instance name="intershop.SMBWebShop" with="ApplicationType">
           <fulfill requirement="id" value="intershop.SMBWebShop" />
           <fulfill requirement="urlIdentifier" value="smb-web-shop" />
           <fulfill requirement="cartridgeListProvider" with="intershop.SMBWebShop.Cartridges" />
   		...
       </instance>
   	...
   </components>
   

 After this step we have a project set up with the standard Responsive Starter Store that fits to the application type that was used in the original project.

Remove the Custom Storefront Cartridges

Add Migrated Custom Cartridges

Migrate all your custom cartridges that are not storefront customization cartridges and add them to the project assembly. This includes changes to the source structure, the use of Gradle, the dependency declarations etc.

This only should be done for cartridges that extend the Intershop Commerce Management application, System Management application etc. or add basic functionality that is not depending on any previous storefront cartridge like app_sf_webshop or sld_ch_b2_app.

Once all these changes have been applied:

1. Publish your project and deploy the server.

   cd <COMPONENTSET>
   gradlew publish
   gradlew deployServer

Migrate the Project Data (except for the CMS Content)

Use dbmigrate to migrate the project data from your current Intershop version to the intended newer Intershop version, see Cookbook - DBMigrate and Concept - DBMigrate and DBInit for details.

With this step your product data, customer data, etc. is migrated to the new Intershop version. Only the previously removed CMS content is not migrated since this cannot be done automatically anyways.

Remove All Branding Packages

Since the content and the structure of branding packages was changed in the Responsive Starter Store and the CSS classes of the Responsive Starter Store are completely different from the PrimeTech reference store, it is necessary to:

1. Completely remove any installed storefront branding packages via the Commerce Management application to get the styling of the Responsive Starter Store.

Initialize the Storefront with White-label Content 

To get an initial state of the Responsive Starter Store content into the projects storefront one could start to create and assign page variants and components via the Commerce Management application, or one could use the provided white-label content that comes as part of the downloaded Responsive Starter Store. The Concept - White Label Store explains the process in detail but the basic steps for a migrated project that does not itself include the demo_responsive_content cartridge of the Responsive Starter Store are the following:

1. Make sure your projects target application has no pagelets.
   This should be the case since the whole CMS content was remove earlier on.

2. Create the needed whitestore-democontent.zip from the Responsive Starter Store by zipping the folder a_responsive\demo_responsive_content\staticfiles\share\sites\inSPIRED-inTRONICS-Site\units\inSPIRED-inTRONICS-b2c-responsive\impex\src\white-label store.

   for smb/b2b applications

   Create the needed whitestore-democontent.zip from the Responsive Starter Store by zipping the folder a_responsive\demo_responsive_content\staticfiles\share\sites\inSPIRED-inTRONICS_Business-Site\units\inSPIRED-inTRONICS_Business-smb-responsive\impex\src\white-label store.

   In case your are not only using the plain smb application but the b2b application the content of a_responsive\demo_responsive_b2b\staticfiles\share\sites\inSPIRED-inTRONICS_Business-Site\units\inSPIRED-inTRONICS_Business-smb-responsive\impex\src\white-label store needs to be added to the whitestore-democontent.zip too.
   

   The zip files folder structure should look like that:

   whitestore-democontent.zip ├── component ├── componenttemplate ├── enfinity ├── include ├── META-INF ├── page ├── pagetemplate ├── pagevariant └── viewcontext

3. Copy the whitestore-democontent.zip to your servers shared file system to <IS_SHARE>\sites\<YourOrganization-YourChannel>Site\units\ <YourOrganization-YourChannel-YourApplication> \impex\src .

4. Lo into the Commerce Management application, switch to your now Responsive Starter Store based storefront application and go to Content > Import & Export.
   There the option Prepare application content should be available.

5. Click the Prepare button.
   This starts an import process of the whitestore-democontent.zip into your application and should finish without any errors.
   

6. Click on Preview in the main navigation should bring you to the with default content prepared Responsive Starter Store storefront.

Migrate Required Parts of the Project Content Model

After the Intershop Commerce Management base is migrated and a standard Responsive Starter Store storefront is running on top of it it is a good point to:

1. Migrate relevant parts of the old customized content model, meaning content model files (*.pagelet2 files) that where implemented to meet custom requirements that still exist.
   This basically means to identify parts of your content model customizations that are not mainly for layout or functionality purposes (like Container, Cart, Header, Main Navigation etc.) but that carry content (like Free Style HTML or Image components) that should still be used in the new Responsive Starter Store storefront.

Once the relevant parts of your content model are identified, it is necessary to:

1. Migrate these model files with the changes introduced between your Intershop source and target version. The code migration parts of the following migration guides may help identifying necessary changes:
   1. Guide - 7.4 Migration Guide Application Awareness for CMS
   2. Guide - 7.5 Content Model Migration
   3. Guide - 7.6 Migration to Responsive Starter Store
2. With this step it is not only necessary to fit the content model format changes but references between the components need to be adjusted too.
   So custom components will be assignable to slots of the Responsive Starter Store content model.
3. Once the changes are complete it is necessary to publish and deploy your project and start the server.
   This is a pre-requisit to import of the migrated CMS content in the next step.

Migrate Relevant Parts of the Exported CMS Content

Migrate Content in Import/Export Files

The following steps are manual steps with a capable text editor or any scripting tool of your choice.

1. Extract the the exported and downloaded content ZIP files.
   You will have a different ZIP file for any organization, channel, or application that had own content managed in it. The ZIP files need to be extracted in a way that allows zip-packing them again in the same way as before but with the necessary migration changes.
2. The necessary steps are pretty much the same for any origination (organization, channel or application). They can be done for all CMS exports together or for each origination separately.

In general the content of CMS export files should look similar to the below directory listing.

The root directory of this listing is usually the place for any batch operation in case the migration is done export file by export file. If the migration is done for all content exports it will be a collection of such root directories.

There are probably only a few components that stayed similar between your Intershop source version and the Responsive Starter Store content model that could be mapped between the two content models. This applies mainly for the components that do actually contain content but are not heavily involved in the storefront configuration, like the Freestyle HTML and Image components.

1. Adapt the old components (previous content model) from the export files to be imported again in the new content model.

   Old content model		Responsive Starter Store Content Model
   comp.common.freeStyle.pagelet2	Common - Freestyle HTML Text	Free Style HTML	component.common.freeStyle.pagelet2
   comp.common.imageTeaser.pagelet2	Common - Image Teaser	Image	component.common.image.pagelet2

2. On top of the components that can be mapped between the standard Intershop content models, the migrated, required parts of the project content model (see step before) need to be migrated in the Import/Export files too.

   The following steps will be necessary on these Import/Export files to only include the relevant parts of migrated CMS content.

   1. Delete all instances of no longer used component types or no longer needed instances.
   2. Remove pagelet assignment information that is no longer valid due to a changed content structure.
   3. Add or replace the Resource Set IDs (regarding application awareness model changes).
   4. Delete removed slots information.

Import Migrated Content

After applying all the manual migrating steps:

1. Zip-pack the content import files again.
2. Upload the package to the server.
3. Run the import and check for any import errors.
4. If there are errors logged, remove the problems from the Import/Export files and repeat the import process.

Once the content import is executed without errors or warnings the content migration on the import files is done. All remaining steps can be done on the server.

Fit the Migrated Content to the New Responsive Starter Store Styling and Structure

After successfully migrating the storefront and importing the relevant CMS content it is a good time to check the result in the storefront.

At this point it is necessary to use the Data View or the Design View to further edit content, especially the Freestyle HTML components. Here the CSS classes and the HTML structure needs to be adjusted to the Responsive Starter Store.

Migrate Storefront Customization

Once the basic migration is done and the storefront is running on top of the Responsive Starter Store cartridges the migration of custom features to the Responsive Starter Store can be tackled.