Guide - 7.8 Migration Hints

1 Introduction

Intershop Commerce Management 7.8 comes with new assembly, build and deployment tools. While 7.8-based projects should exclusively use the Intershop Gradle Tools 2.11, the new version of the tools can also be used alongside with Intershop Commerce Management 7.6 and 7.7.

Gradle Tools 2.11 are based on Gradle 2.11.

1.1 Important Documents

2 Upgrade / Update Sequence

  1. Update the ISH Gradle Tools.
    See section Migrate Tools Version for details.
  2. Adapt projects based on ICM 7.6 or 7.7 to new project structure.
    See section Migrate the Project Structure for details.
  3. Carefully examine Overview - 7.7-7.8 Migration and its subsequent pages to determine whether project specific migration steps are required.
    1. Besides the database changes there are changes for various artifacts, e.g., pipelines, pipelets, pagelets, Java classes and methods etc.
      Please refer to Guide - 7.8 API Changes, see column How to migrate to learn what task have to be performed to migrate your existing Web Shop from 7.7 to 7.8.
  4. Execute DBmigrate.

3 Migrate Tools Version

To use Gradle Tools 2.11 with Intershop Commerce Management 7.6 or 7.7, perform the following steps to migrate your environment:

  1. Ensure to have access to the public repository of Intershop.
  2. Adapt your repository configuration of the artifact repository.
    Follow the Recipe: Configure Artifact Repository Server in Cookbook - Setup CI Infrastructure.
  3. Update or create a corporate distribution as described in Recipe: Create Sources From Intershop Templates in Cookbook - Setup CI Infrastructure.
    Run the tasks createCorporateDistribution.
  4. Build the corporate distribution by triggering the automated CI processes.
  5. For your component set project, perform the following steps:
    • Change the Gradle distribution used by the Gradle Wrapper by modifying the property distributionUrl in gradle/wrapper/gradle-wrapper.properties.
    • In your gradle.properties files, remove the following properties if they exist:

      Outdated gradle.properties
      filter.com.intershop.build.set.cartridge-plugins
      filter.com.intershop.build.set.extension-plugins
      version.com.intershop.deployment-bootstrap

      and add the following property instead:

      New gradle.properties for updated Gradle Tools
      filter.com.intershop.build.gradle.gradle-tools = 2.11.4
      version.com.intershop.build.gradle.deployment-launcher = 2.11.4

      For more information regarding deployment-bootstrap, see section Product-Specific Deployment Components in Platform.

  6. Use the sources of the Responsive Starter Store to configure the project (Recipe: Create Sources From Intershop Templates in Cookbook - Setup CI Infrastructure).

    Note

    Intershop recommends to change the project structure to reduce the efforts for the development, the build itself and the maintenance of a build.

    1. Copy your assembly in the Gradle project with the store cartridges and adapt your assembly according to the sources of the assembly in the original source package.

    2. Adapt your release process.
      If it is not possible to use the SCM Versioning plugin or the provided release plugins, you can use a static version configuration. Furthermore it is possible to create your own publishing plugin. The sources of all public available Intershop Gradle plugins are available on GitHub (https://github.com/IntershopCommunicationsAG).
    3. Adapt your CI configuration as described in Recipe - Setup CI Build For Project Artifacts in Cookbook - Setup CI Infrastructure

4 Migrate the Project Structure

Intershop delivers a Responsive Starter Store for an easy project start. There is a project with sources for components - component set 'a_responsive' - and an assembly project 'insprired-b2x' or 'inspired-b2c'. These projects were renamed with the creation of the project. The present document uses the original names for the migration of the projects. 'inspired-b2x' is a synonym for 'inspired-b2x' and 'inspired-b2c'.

Please use the document Cookbook - Setup CI Infrastructure for your changes on the CI process.

  1. Adapt your repository configuration. Verify your configuration with Recipe: Configure Artifact Repository Server.
  2. Create the necessary sources for the CI setup. See Recipe: Create Sources From Intershop Templates).
  3. Create a new corporate distribution, follow the instructions in Recipe: Setup CI Build for Corporate Artifacts. It is not necessary to change or add a new build of 'p_oracle'.
  4. Stop your CI processes.

For the migration of your project, we use the generated sources of createProject. The source are located in <sources>/projects/<project name, e.g., corporateshop>.

  1. Update Gradle and Gradle build tools for the component set project.
    1. Copy the content of <sources>/projects/<project name, e.g., corporateshop> to the component set. Existing files must be overwritten.

    2. Update your gradle.properties.
      Change

      Outdated version
      filter.com.intershop.build.set.cartridge-plugins = 2.7.1

      to

      New version
      filter.com.intershop.build.gradle.gradle-tools = 2.11.4
      version.com.intershop.deployment-bootstrap = 2.11.4
    3. Update your build.gradle.
      Use the template build.gradle and replace the following placeholder:

      PlaceholderContent
      <project description>Project description
      <project group>Group of the project, e.g., com.company.project
      <assembly name>Name of the assembly project
      <sonar-host>

      Host name of the SonarQube server. If no SonarQube is used in the project, it is possible to remove the SonarQube Gradle plugin.
      Remove the following lines from the build.gradle file.

      Remove SonarQube Gradle plugin
      apply plugin: 'com.intershop.gradle.sonarQube'
       
      sonarqube {
      	sonarProperties {
          	property 'sonar.host.url', 'https://<sonar-host>'
      	}
      }

      It is also necessary to change the configuration com.intershop.assembly:commerce_management_b2x to com.intershop.assembly:commerce_management_b2c, if you use only Intershop Commerce Management B2C.

    4. Update your settings.gradle.
      Use the template settings.gradle and replace the following placeholder:

      Placeholder

      Content
      <project name>project name
  2. Update Gradle and Gradle build tools for the assembly project.

    1. Copy the assembly project in the component set.

      Using Subversion it is possible to use svn cp.

    2. Remove the following files and directories from the copied assembly project:
      • bin
      • extbuild.gradle
      • settings.gradle
      • gradlew
      • gradlew.bat
      • gradle.properties
    1. Adapt the build.gradle of the assembly.
      • Remove group and version configuration.

        Remove from build.gradle
        group = '<group>'
        version = '<version>'
      • Replace plugin and dependency configuration.

        Old configuration
         buildscript { 
        	repositories { maven { ... } } 
        	dependencies { 
        		classpath 'com.intershop.build.gradle:ish-assembly' 
        		classpath 'com.intershop.build.gradle:plugin-tests' 
        		classpath 'com.intershop.build.release:intershop-buildinfo-plugin:2.2.8' 
        	} 
        } 
         
        apply plugin: 'ish-assembly' 
        apply plugin: 'ish-assembly-branding' 
        apply plugin: 'buildinfo'
        New configuration
         buildscript {
            dependencies {
                classpath 'com.intershop.build.gradle:ish-assembly'
                classpath 'com.intershop.build.gradle:plugin-tests'
        
                classpath 'com.github.groovy-wslite:groovy-wslite:1.+'
            }
        }
        
        apply plugin: 'ish-assembly'
        apply plugin: 'ish-assembly-branding'
        // optional
        apply plugin: 'project-report'
        apply plugin: 'jacoco'
      • Change the declaration of dependencies.
        In the assembly block replace all dependencies contained in your component set with project dependencies, e.g., com.intershop.foo:bar becomes project(':bar').
        In the cartridges block replace all programmatic dependency declarations for cartridges contained in your component set with project dependencies, e.g., fooCartridges.collect {"com.intershop.foo:$it"} becomes fooCartridges.collect { project(":$it") }
  3. Test your changes.
    Execute gradlew publish and gradlew deployServer.

    Note

    It is necessary to configure your Gradle environment, before you run the commands. Please use the available scripts.

  4. Commit the changes to your version control system.
  5. Adapt your CI configuration following the documentation Recipe: Setup CI Build for Project Artifacts in Cookbook - Setup CI Infrastructure.

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