• v3.0
    • Versions
    • master
    • v3.0
    • v2.3
    • v2.2
    • v2.1
    • v2.0
    • v1.7
    • v1.6
    • v1.5
    • v1.4
    • v1.3
    • v1.2
    • v1.1
    • v1.0

 

  • Install Akeneo PIM
    • Install Akeneo PIM with Docker
    • Install Akeneo PIM manually
      • System Requirements
      • System installation on Debian 9 (Stretch)
      • System installation on Ubuntu 16.04 (Xenial Xerus)
      • Installing Akeneo PIM Community Edition (CE) with the Archive
      • Installing Akeneo PIM Enterprise Edition (EE) with the Archive
      • Setting up the job queue daemon
    • How to customize the Dataset
    • How to Add Translation Packs
  • Migrate Akeneo PIM projects
  • Import and Export data
    • How import works
    • Understanding the Product Import
    • Understanding the Product Export
    • Formats
      • Localized labels
      • Scopable labels
      • Association types data structure
      • Attribute data structure
      • Category data structure
      • Family data structure
      • Family variant data structure
      • Group data structure
      • Options data structure
      • Product data structure
      • Product model data structure
    • Akeneo Connectors
    • How to Customize Import / Export
      • How to create a new Connector
      • How to import Products from a XML file
      • How to clean a CSV file during a Product import
      • How to automate imports/exports
  • Manipulate the Akeneo PIM data
    • How to Customize Mass Edit Operations
      • How to register a new bulk action
      • How to Register a New Mass Edit Action on Products
      • How to Avoid Rules Execution on Mass Edit Actions
    • How to Manipulate Products
      • How to Query Products
      • How to Create Products
      • How to Update Products
      • How to Validate Products
      • How to Save Products
      • How to Remove Products
    • How to Manipulate Non-Product Objects
      • How to Query Non-Product Objects
      • How to Create Non-Product Objects
      • How to Update Non-Product Objects
      • How to Validate Non-Product Objects
      • How to Save Non-Product Objects
      • How to Remove Non-Product Objects
    • How to add a custom action rule
      • General information about rule format
      • How to add a custom action in the rule engine
    • How to Define Access Control List
    • How to Customize the Catalog Structure
      • How to Create a Reference Data
      • How to add a custom unit of measure
      • How to Add New Properties to a Category
    • How to Customize Product Assets
      • How to Add a New Transformation
      • How to Add a Default Thumbnail For Unknown File Types
      • How to connect to an external server for storage
      • How to change the validation rule to match a reference file to an asset
      • How to Mass Import Assets
    • How To Customize Teamwork Assistant (Enterprise Edition)
      • Customize notifications
      • Add a calculation step
      • How to log calculation step
      • Remove projects impacted by a custom catalog update
  • Design the user interfaces
    • How to customize any frontend part of the application
    • How to add an action button or meta data to the product edit form
    • How to add a tab to a form
    • How to add a new tab in System / Configuration
    • How to add custom information to a field
    • How to add a new field type
    • Create a custom product export builder filter
    • How to create the UI to manage a Reference Data
    • How to add a new page
    • How to customize the main menu
    • Styleguide
  • Maintain Akeneo PIM projects
    • First aid kit
    • Bug qualification
    • Common issues
    • Scalability Guide
      • Audit with 3 Representative Catalogs
      • More than 10k attributes?
      • More than 10k families?
      • More than 10k categories?
      • More than 500 attributes usable in the product grids?
      • More than 100k products to export?
      • More than 1GB of product media to export?
    • How to purge history
      • How to Purge jobs executions
      • How to adapt the version purger to your needs
  • Contribute to Akeneo PIM
    • How to report an issue?
    • How to translate the user interface?
    • How to enhance the documentation?
    • How to contribute to a Connector?
    • How to submit a patch to the PIM?
    • How to contribute to the frontend part of the application
    • How behavior tests are architectured in the PIM?
      • Establishing Decorator Pattern
      • Using Spin In Behat
  • Use SSO authentication locally
  • Technical overview
    • Product Information
    • Teamwork Assistant (Enterprise Edition)
      • Project creation
      • Project completeness
      • Project Completeness widget
      • Catalog update impact
      • Scalability guide
      • Users permission summary for Behat tests
    • Collaborative workflow
      • Simple workflow
      • Partial workflow
  • Technical architecture
    • Best Practices
      • Create a project
      • Create a reusable bundle
      • Setup Behat
      • Code Conventions
      • Coding Standards
    • How to implement your business logic using the event system
    • Events
      • Storage events
      • Workflow events (Enterprise Edition only)
    • How to Localize your data
      • How to change the PIM locale
      • How to Use Localizers
      • How to use Presenters
    • How to Add a Notification
    • Performances Guide
      • Memory usage of rules execution (Enterprise Edition)
      • Memory leak fix in Rules Engine (ORM)
      • More than 100 WYSIWYG editors in a page
      • PHP7 and HHVM Compatibility?
      • Job product batch size
    • How to Use the Web REST API
    • Standard format
      • Products
      • Other entities
      • Usage
    • Application Technical Information
      • Application Technical Dependencies
      • Server side set up for hosting
      • System Requirements
      • Recommended configuration
      • Client side configuration and compatibilities
      • Operation processes
      • Flow Matrix
  • Akeneo Cloud Edition
    • Flexibility Mode
      • Overview
      • Partners Starterkit
      • Environments Access
      • Composer settings
      • Periodic tasks / Crontab settings
      • PIM Application
      • PIM Updates and Migrations
      • Data File Transfer
      • Backups management
      • Partners
      • System Components
    • Serenity Mode
      • Overview
      • PIM Updates and Migrations
  • Akeneo Onboarder
    • Prerequisites
    • Installation
    • Synchronization
    • Environment variables
      • Using the DotEnv file
      • Using environment variables

Migrate Akeneo PIM projects¶

This chapter describes how to apply a patch on your current version or how to upgrade from a minor/major version to a more recent one.

As a prerequisite, we assume that you are using a project installed from a Community Standard (Install Akeneo PIM).

How to apply a patch?¶

We frequently release patches for all supported versions - you can find the list of supported versions in this article How many PIM Enterprise Edition versions are maintained by Akeneo?

Each patch contains bug fixes and sometimes improvements or security fixes, that is why it is very important to always have the latest patch installed on your PIM. Also for support purposes, if you experience an issue, make sure your PIM is up-to-date before raising a ticket to our Support team.

When our maintenance team works on issues, they take extreme care to avoid any backward compatibility break, but it might happen. If it is the case, the BC break is mentioned in the changelog of the version.

Akeneo PIM CE changelog is available on our GitHub repository:

  • Go to our Community Repository.
  • Select your branch in the drop down menu, for instance select 3.0 branch.
  • Then scroll down the page, and select the desired Changelog in the list, for instance Changelog 3.0 version.

Note

Akeneo provides 2 changelogs: one for CE edition available the Community repo and one for EE edition which is only available in the latest archive. If you want to check the latest fixes for the Enterprise Edition, download the last archive or contact us.

In the following example, Akeneo PIM version 3.0.10 has just been released and we are using an Akeneo PIM version 3.0.9.

Community Edition

Run the composer update command:

php composer.phar --prefer-dist update

Be aware that your composer.json won’t be updated and some dependencies might be missing or from an outdated version.

You have to check whether the latest composer.json is different from your own. In this case you should backup your current composer.json and download the newest one beforehand.

Double check in the output of this command that the 3.0.10 version has been fetched, you can also check it by using the following command:

php composer.phar licenses

Then clean the cache, re-install assets and warmup the cache:

Note

Before launching the following commands, remember to stop the daemon to avoid generating outdated cache.

service php7.2-fpm restart
rm -rf var/cache/* ./web/bundles/* ./web/css/* ./web/js/*
bin/console --env=prod pim:installer:assets
bin/console --env=prod cache:warmup
yarn run webpack

If the patch is a javascript fix, please clear your browser cache before testing.

Note

We set any other dependencies to their exact patch versions to avoid compatibility issues. We strongly advise you to add the composer.lock in your versioning system.

Note

If you get a 500 error after upgrading and clear cache isn’t working try to clear the apc cache with a php script or restart Apache/Web server.

Enterprise Edition

Please follow Community steps and then Enterprise Edition steps.

In your enterprise standard project, the composer.json will reference both community and enterprise bundles repositories.

To upgrade, please change the composer.json to:

{
    ...
    "akeneo/pim-enterprise-dev": "3.0.10",
    "akeneo/pim-community-dev": "3.0.10",
    ...
}

We always tag both community and enterprise versions with aligned version numbers, be sure to use the exact same version for CE and EE, for instance, a EE 3.0.10 fix may depend on CE 3.0.10.

Using the exact patch version will avoid any local composer cache issue.

Then run the composer update command:

php composer.phar --prefer-dist update

Then follow the same process as the one for the community edition:

Note

Before launching the following commands, remember to stop the daemon to avoid generating outdated cache.

service php7.2-fpm restart
rm -rf var/cache/* ./web/bundles/* ./web/css/* ./web/js/*
bin/console --env=prod pim:installer:assets
bin/console --env=prod cache:warmup
yarn run webpack

For Akeneo Cloud environments

You can follow this process:

partners_clear_cache
bin/console --env=prod pim:installer:assets
yarn run webpack

Note

Use the partners_clear_cache command available on Partners.

How to upgrade to a minor version?¶

We release a minor version every 3 months, these versions bring new features.

Depending on these features and on the custom code you’ve added in your project, the migration can be more or less straightforward.

Each release is provided with a migration guide and a set of scripts to automate it as much as possible.

We continue to improve this process to make every new migration easier than the previous one.

Here are the migration guides:

Community Edition

  • From v2.3 to v3.0
  • From v2.2 to v2.3
  • From v2.1 to v2.2
  • From v2.0 to v2.1
  • From v1.6 to v1.7
  • From v1.5 to v1.6
  • From v1.4 to v1.5
  • From v1.3 to v1.4
  • From v1.2 to v1.3
  • From v1.1 to v1.2
  • From v1.0 to v1.1

Enterprise Edition

Standard Enterprise Edition (EE) archives are available from the Portal.

Then, follow the migration guides located in your archive to upgrade your project.

  • From EE v2.3 to EE v3.0: UPGRADE-3.0.md
  • From EE v2.2 to EE v2.3: UPGRADE-2.3.md
  • From EE v2.1 to EE v2.2: UPGRADE-2.2.md
  • From EE v2.0 to EE v2.1: UPGRADE-2.1.md
  • From EE v1.6 to EE v1.7: UPGRADE-1.7.md
  • From EE v1.5 to EE v1.6: UPGRADE-1.6.md
  • From EE v1.4 to EE v1.5: UPGRADE-1.5.md
  • From CE v1.4 to EE v1.4: UPGRADE-CE-1.4-EE-1.4.md
  • From EE v1.3 to EE v1.4: UPGRADE-1.4.md
  • From EE v1.0 to EE v1.3: UPGRADE-1.3.md

How to upgrade to a major version?¶

We release a major version each year, these new major versions bring new features and larger changes to answer clients growing needs.

To migrate from 1.7 to 2.0, we recommend the use of our brand new migration tool Transporteo.

We’re continuously improving Transporteo to cover more and more use cases and automate more and more the migrations.


Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!