Guide - 7.6 Migration to Responsive Starter Store

1 Introduction

This document describes the necessary migration steps to swap from an Intershop 7.6 PrimeTech (app_sf_webshop) based storefront to the storefront of the Responsive Starter Store (app_sf_responsive). After these steps the storefront will have the look and feel of the Responsive Starter Store. This is a completely manual migration procedure and there is and will be no automatic process for this.

Since the content model of the Responsive Starter Store is derived from theapp_sf_webshop content model and since it was only slightly changed, it is possible to migrate from one content model to the other. This document will show the necessary steps from a plain app_sf_webshop installation to plain app_sf_responsive. For any attempt to do this migration in a custom project context it will be effort relevant especially how much the content model ofapp_sf_webshop has been customized. Migrating an non-app_sf_webshop-based project to the Responsive Starter Store may be more difficult. In that case this documentation might be a starting point but not a step by step guide.

As preliminary work, the migration steps of the Guide - 7.6 Migration of a PrimeTech Based Storefront are required for any attempt to migrate to the Responsive Starter Store storefront. Be sure to read this prior to the present document.

This following screenshot shows the Homepage of the PrimeTech Specials demo storefront before the migration to the Responsive Starter Store.

The following steps describe the migration based on the PrimeTech demo scenario.

2 Steps

As for any such attempt a system backup is highly advised (e.g., "ant export").

2.1 Export CMS Content - Backup

  1. Export all CMS content of all organizations, channels and applications, preferably as ZIP export.
    The content of these ZIP files will later on be the base for the manual transformation and will be re-imported as the new Responsive Starter Store content.

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

2.2 Migrate Custom Cartridges (Basic)

Before migrating the basic configuration of the projects component set, application types and assembly it is probably best to first do a basic migration of your custom storefront code. This means:

  1. Change all dependencies to the app_sf_webshop cartridge or artifacts from within your custom cartridges to the according ones located in app_sf_responsive.
  2. Perform a simple text search for app_sf_webshop over all artifacts (*.isml, *.xml etc.) in all your custom cartridges.
  3. Replace with app_sf_responsive.
    You are done if no references to app_sf_webshop are found.

Basically the following references need to be replaced:

  • References between content model definitions (*.pagelet2)
  • References to slots or system manged includes in ISML templates
  • References to system manged pages or includes in pipelines
  • Cartridge dependency definitions (build.gradle)

After changing those references your custom cartridges should have undergone a basic migration to work with the Responsive Starter Store.

Be sure to complete this step as it is necessary to get a consistent content model that is based onapp_sf_responsive also for the custom parts. Only in this way it will later be possible to successfully migrate the CMS content (export files from above) for the custom content model parts too.

Migration of Custom Code

Depending on the amount of customization, there is still some work to do to fit your custom code to the new storefront styling, behavior or any functional changes of the Responsive Starter Store. This will include:

  • Changes to the implemented HTML structure
  • Changes to the CSS styling (e.g., working with Less)
  • Pipeline adaptions
  • ...

It is probably best to do these steps once the basic migration of the storefront - as described in these chapters - to the Responsive Starter Store is done and the server is running on the new storefront base.

The following steps will describe the migration process for the PrimeTech demo scenario only. This is a basic guide to get an impression on the steps to be done. For custom projects there might be additional changes that need to be considered.

2.3 Migrate Component Set

To migrate the projects component set to be based on the Responsive Starter Store one has to copy the Responsive Starter Store storefront cartridges to the projects component set (similar to the Recipe: Set Up Project Based on the Responsive Starter Store).

The table gives an overview of the needed cartridges for the different assembly types.

Assembly TypeStorefront Cartridges
B2C

app_sf_responsive
app_sf_responsive_cm
app_sf_responsive_b2c
app_sf_responsive_smb
as_responsive

B2X

B2C Storefront Cartridges +
app_sf_responsive_b2b
app_sf_responsive_costcenter
as_responsive_b2b


In addition the following changes have to be made to the component sets configuration:

  1. Declare the 3rd party dependencies.

    build.gradle
        dependencies {
            // required for isml2classMain
            compile 'org.slf4j:slf4j-api'
            compile 'ch.qos.logback:logback-core'
            compile 'org.apache.tomcat:tomcat-el-api'
    
            compile 'javax.inject:javax.inject'
            compile 'com.google.inject:guice'
        }
  2. Define the build dependency to the Less pre-processor.

    build.gradle
    buildscript {
        dependencies {
            classpath group: 'com.intershop.build.gradle', name: 'ish-component-plugin'
            classpath group: 'com.intershop.build.gradle', name: 'assembly'
    
            classpath "org.lesscss:lesscss:1.7.0.1.1"
        }
    }

    Once all these changes have been applied,

  3. Publish the component set.

    cd <COMPONENTSET>
    gradlew publish

    If this does not result in "BUILD SUCCESSFUL" additional migration changes are needed according to the given failure messages.

2.4 Migrate the Storefront Application Type

For a migration scenario from anapp_sf_webshop-based storefront to the Responsive Starter Store storefront withapp_sf_responsive 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 already usedas_primetech need to be kept. There is no easy way to migrate the application types of existing application instances. Only the used set of cartridges needs to be changed.

For this, the projects application types definition cartridge (e.g.as_responsive) should include theapps.component file of as_primetech with the following changes:

<DIFF> apps.component
<instance name="intershop.B2CWebShop.Cartridges" with="CartridgeListProvider">
-   <fulfill requirement="selectedCartridge" value="app_sf_webshop_b2c"/>
-   <fulfill requirement="selectedCartridge" value="app_sf_webshop_cm"/>

+   <fulfill requirement="selectedCartridge" value="app_sf_responsive_b2c"/>
+   <fulfill requirement="selectedCartridge" value="app_sf_responsive_cm"/>

...

<instance name="intershop.SMBWebShop.Cartridges" with="CartridgeListProvider">
-   <fulfill requirement="selectedCartridge" value="app_sf_webshop_smb"/>
-   <fulfill requirement="selectedCartridge" value="app_sf_webshop_cm"/>

+   <fulfill requirement="selectedCartridge" value="app_sf_responsive_smb"/>
+   <fulfill requirement="selectedCartridge" value="app_sf_responsive_cm"/>

For a B2B project additional cartridge dependencies will have to be fulfilled for the intershop.SMBWebShop application type. The required set can be found here:
a_responsive\as_responsive_b2b\staticfiles\cartridge\components\apps-extension.component.

Once all these changes have been applied the component set needs to be published again.

cd <COMPONENTSET>
gradlew publish

2.5 Migrate Assembly

Migrating the assembly to the Responsive Starter Store basically means removing the usage of the previous app_sf_webshop* cartridges from the assembly while adding theapp_sf_responsive* cartridges.

For this the following steps are needed:

  1. Change the build.gradle of the assembly.

    <DIFF> build.gradle
    group = 'com.example.foo'
    buildscript {
        dependencies {
            classpath 'com.intershop.build.gradle:ish-assembly'
            classpath 'com.intershop.build.gradle:plugin-tests'
        }
    }
    apply plugin: 'ish-assembly'
    assembly {
        inheritFrom('com.intershop.assembly:commerce_management_b2c') {
            includeArtifacts type:['deploy-settings-gradle','deploy-gradle']
        }
    
        cartridges {
    
    -        def primetechCartridges = [
    -            'app_sf_webshop',
    -            'app_sf_webshop_cm',
    -            'app_sf_webshop_b2c',
    -            'app_sf_webshop_smb',
    -            'as_primetech'
    -        ]
    -        include(*(primetechCartridges.collect {"com.intershop.primetech:$it"}), in:[development, test, production])
    
            def projectCartridges =
            [
    +            'app_sf_responsive',
    +            'app_sf_responsive_cm',
    +            'app_sf_responsive_b2c',
    +            'app_sf_responsive_smb',
    +            'as_responsive',
                'my_cartridge'
            ]
            include (*(projectCartridges.collect {"com.example.foo:$it"}), in:[development, test, production])
    
            def initCartridges = [
                'my_demo'
            ]
            include (*(initCartridges.collect {"com.example.foo:$it"}), in: init)
    
    -        order = listFromAssembly('com.intershop.assembly:commerce_management_b2c') + primetechCartridges + projectCartridges + initCartridges
    +        order = listFromAssembly('com.intershop.assembly:commerce_management_b2c') + projectCartridges + initCartridges
        }
        extraAttributes = [
                'productName': 'Intershop 7',
                'copyrightOwner': 'Intershop Communications',
                'copyrightFrom': '2005'
            ]
    }
    assemblyBuild {
        database {
            inherit('com.intershop.assembly:commerce_management_b2c')
            initCartridges = [
    -            'app_sf_webshop',
    +            'app_sf_responsive',
                'my_demo'
            ]
        }
    }
    dependencies {
        testCompile "com.intershop.build.gradle:ish-common"
        testCompile "com.intershop.build.gradle:ish-assembly-test"
    }
    configurations.all {
        exclude group: 'asm', module: 'asm'
    }

    Once all these changes have been applied,

  2. Publish the assembly.

    cd <ASSEMBLY>
    gradlew publish

    If this does not result in "BUILD SUCCESSFUL" additional migration changes are needed according to the given failure messages.

    After a successful publishing,

  3. Deploy the assembly.

    gradlew deployServer

Once the server is successfully deployed it can be started. Doing so you get a server that already has the Responsive Starter Store functionality but no working content yet. Therefore the storefront will render empty or with an error. Migrating the content will be addressed in the next section.

2.6 Migrate CMS Content

2.6.1 Remove Invalid Content from Database

Before migrating the exported and downloaded content it is necessary to get rid of the existing content in the database that is now invalid due to changes to the content model. We no longer use the old app_sf_webshop content model but the server now only knows theapp_sf_responsive content model.

This clean up is a precondition for importing the manually migrated content.

To remove any invalid CMS content instances Intershop provides a job that can be run from the SMC.

  1. Execute the job Synchronize Page Model and Pagelet Instances in the SLDSystem domain.
    Doing so completely removes all the instances that no longer fit to any content model definition. In the present case it completely removes the old obsolete CMS instances from the database.

2.6.2 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. See the following sub sections for details.

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

<CMS_EXPORT_FILE_CONTENT>
├── component
├── componenttemplate
├── enfinity
├── include
├── META-INF
├── page
├── pagetemplate
├── pagevariant
└── viewcontext

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.

2.6.2.1 Replace the Resource Set IDs

  1. Replace the all the old resource set ID app_sf_webshop by app_sf_responsive.
    A simple search and replace function over all the CMS export files will be enough to change that.
  2. Replace app_sf_webshop_cm with app_sf_responsive_cm too.

Test and adapt cycle

After that it would already be possible to re-zip the changed files and upload the content import archive to a migrated server without any content (see Remove invalid content from database). A complete import of the archive can be done to check what and how many errors or warnings still come up. These log messages basically give an idea on what still needs to be done for migrating the CMS content.

This testing step can be repeated for any of the following content migration steps. Before doing that it is necessary to remove all previous content again.

2.6.2.2 Delete Instances of Removed Component Types

app_sf_webshop component types that are no longer available in app_sf_responsive:

  • Animated Marketing Teaser (component.common.animatedMarketingTeaser)
    (a similar component type of the Responsive Starter Store is called Carousel)
  1. Search for "component.common.animatedMarketingTeaser.pagelet2".
  2. Memorize the according pagelet-component id value.
    You need the ID to identify all pagelet assignment elements in step 4.
  3. Remove all instances of that component type search.
  4. Any pagelet assignment element which refers to these memorized IDs need to be removed too.

2.6.2.3 Delete Removed Slots

The component types component.checkout.emptyCart.pagelet2 and component.checkout.cart.pagelet2 of app_sf_responsive no longer have the slot.marketing.sidePanel.pagelet2 slot. Therefore,

  1. Remove the according slot references in all instances of these two component types.

    Slot definition block that needs to be removed
    <slot>
    <definition-name>app_sf_responsive_cm:slot.marketing.sidePanel.pagelet2-Slot</definition-name>
    <optional>false</optional>
    <sorting>false</sorting>
    </slot>
    
  2. Remove or change all pagelet assignment elements and all placeholder definitions pointing to this slot (e.g., pointing it to the other slot of these component types - slot.marketing.content.pagelet2)

    Example Pagelet Slot Assignment that needs to be changed
    <pagelet-slot-assignment id="XGgKAM4.xdEAAAE_5axV6D1q">
    <slot definition-name="app_sf_webshop_cm:slot.marketing.sidePanel.pagelet2-Slot" parent-pagelet-id="cmp_emptyCart" domain="PrimeTech-PrimeTechSpecials-b2c-web-shop"/>
    <pagelet id="cmp_cart_productRecommendations" domain="PrimeTech-PrimeTechSpecials-b2c-web-shop"/>
    <position>1</position>
    <online>true</online>
    </pagelet-slot-assignment>

2.6.2.4 Delete Removed Configuration Parameters

component.common.container.pagelet2-Component-Grid
The Grid configuration parameter no longer exists for the Container component in the Responsive Starter Store.

  1. Remove all such occurrences to avoid warnings when importing.

    Grid configuration parameter example
    <configuration-parameter name="Grid">
    <definition-name>app_sf_responsive_cm:component.common.container.pagelet2-Component-Grid</definition-name>
    <value name="Grid">width=24;prefix=0;suffix=0;push=0;pull=0</value>
    </configuration-parameter>
  2. Use the CSSClass configuration parameter and set the needed Bootstrap grid classes to control the width of the Container component.
    It might be helpful to rename the "Grid" parameter occurrences and change their values for the import.

    Grid configuration parameter repurposed as CSSClass parameter
    <configuration-parameter name="CSSClass">
    <definition-name>app_sf_responsive_cm:component.common.container.pagelet2-Component-CSSClass</definition-name>
    <value name="CSSClass">col-xs-12</value>
    </configuration-parameter>

<configuration-parameter name="ListItemGridWidth">
The ListItemGridWidth configuration parameter no longer exists for any component in the Responsive Starter Store.

  1. Remove all such occurrences to avoid warnings when importing.

    ListItemGridWidth configuration parameter example
    <configuration-parameter name="ListItemGridWidth">
    <definition-name>app_sf_responsive_cm:component.common.productListFilter.pagelet2-Component-ListItemGridWidth</definition-name>
    <value name="ListItemGridWidth">4</value>
    </configuration-parameter>

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

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.

2.7 Remove Branding Packages

Since the content and the structure of branding packages was changed in the Responsive Starter Store and since 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 to get the styling of the Responsive Starter Store.

2.8 Fit the CMS Content to the New Responsive Starter Store Styling and Structure

After successfully migrating the storefront and the CMS content of the Responsive Starter Store it is a good time to check the result in the storefront.

Note

At this point it is important that the included project cartridges do not overload any crucial ISML template or pipeline. For example overwriting the DefaultPageStructure.isml might prevent seeing the changed storefront if the overwriting ISML still uses old slots. Be sure to check that upfront.

Using migrated PrimeTech Specials demo content the Homepage will look as:

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 fitted to the Responsive Starter Store. As seen in the picture above, mainly the header and footer content need to be adjusted to fit to the new styling.

Once the content is completely changed to look as expected, it can be exported and used to prepare the content of migrated QA or editing systems.

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

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets