diff --git a/README.md b/README.md index f28ca24..243a3e9 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,6 @@ This tool aims at helping you to migrate your *PIM 1.7 standard edition* (either The 1.7 source PIM you will migrate from can be either installed locally or remotely. The 2.0 destination PIM you will migrate to should be installed locally running on the port 80, you can install it following these [instructions](https://docs.akeneo.com/latest/install_pim/manual/index.html). -We do not support the Docker installation yet regarding Transporteo. The minimum version of the destination PIM is 2.0.3. Both PIM should be functionnal and have a functionnal API with admin rights. @@ -23,7 +22,7 @@ Before proceeding, we strongly encourage you to read our documentation and our f - [Single Product Storage?](https://medium.com/akeneo-labs/single-product-storage-28d92f35cbd7), technical blog post - [Re-building the storage from the ground up](https://medium.com/akeneo-labs/re-building-the-storage-from-the-ground-up-d857bf497c32), technical blog post - [Offer choice with variants!](https://medium.com/akeneo-labs/offer-choice-with-variants-8460a82fa36), functional blog post -- [How Akeneo deals products with variants?](https://medium.com/akeneo-labs/how-does-akeneo-deal-with-variants-42bcab83a879), functional blog post +- [How Akeneo deals with variants?](https://medium.com/akeneo-labs/how-does-akeneo-deal-with-variants-42bcab83a879), functional blog post ## Scope @@ -33,31 +32,31 @@ We count on your feedback to continue to improve it in attempt to cover all your ### Data Migration -Edition | Model | Version | ----------- | ------------------------ | ------------ | -Community | Association type | 1.0.0-alpha1 | -Community | Attribute | 1.0.0-alpha1 | -Community | Attribute Group | 1.0.0-alpha1 | -Community | Categories | 1.0.0-alpha1 | -Community | Family | 1.0.0-alpha1 | -Community | Group type | 1.0.0-alpha1 | -Community | Group | 1.0.0-alpha1 | -Community | Reference Data | 1.0.0-alpha1 | -Community | Product | 1.0.0-alpha1 | -Community | User | 1.0.0-alpha1 | -Community | User Roles | 1.0.0-alpha1 | -Community | User Groups | 1.0.0-alpha1 | -Community | Access Control List | 1.0.0-alpha1 | -Community | Variant Group | 1.0.0-beta1 | -Community | Product History | `-` | -Community | Image files | `-` | -Enterprise | Product Asset | 1.0.0-alpha1 | -Enterprise | Asset files | `-` | -Enterprise | Product Asset Categories | 1.0.0-alpha1 | -Enterprise | Product Rules | 1.0.0-alpha1 | -Enterprise | Product Draft | `-` | -Enterprise | Published Product | `-` | -Enterprise | Teamwork Assistant | `-` | +Edition | Model | Version | +---------- | ------------------------ | ------------------| +Community | Association type | 1.0.0-alpha1 | +Community | Attribute | 1.0.0-alpha1 | +Community | Attribute Group | 1.0.0-alpha1 | +Community | Categories | 1.0.0-alpha1 | +Community | Family | 1.0.0-alpha1 | +Community | Group type | 1.0.0-alpha1 | +Community | Group | 1.0.0-alpha1 | +Community | Reference Data | 1.0.0-alpha1 | +Community | Product | 1.0.0-alpha1 | +Community | User | 1.0.0-alpha1 | +Community | User Roles | 1.0.0-alpha1 | +Community | User Groups | 1.0.0-alpha1 | +Community | Access Control List | 1.0.0-alpha1 | +Community | Variant Group | 1.0.0-beta1 | +Community | Product History | Not supported | +Community | Image files | [See this section](#image-and-asset-files) | +Enterprise | Product Asset | 1.0.0-alpha1 | +Enterprise | Asset files | [See this section](#image-and-asset-files) | +Enterprise | Product Asset Categories | 1.0.0-alpha1 | +Enterprise | Product Rules | 1.0.0-alpha1 | +Enterprise | Product Draft | Not supported | +Enterprise | Published Product | Not supported | +Enterprise | Teamwork Assistant | Not supported | ### Extensions @@ -65,19 +64,7 @@ Extension | Version --------------------- | ------------------------------------------------------------- | ElasticSearchBundle | Not relevant as ElasticSearch is now part of the native stack | InnerVariationBundle | 1.0.0-alpha3 | -CustomEntityBundle | `-` | - -#### InnerVariationBundle - -The modeling of the variations with the IVB must be well structured to be fully handled by Transporteo. In the PIM 2.0, a family variant can't have more than 5 axis, and this axis should be one of the following types: -- Simple select -- Reference data simple select -- Metric -- Yes/No - -If one of these conditions is not fulfilled, the products concerned won't be migrated. You will have to think about a better modeling for these products and migrate them manually. - -You can find the details of the errors in the file "var/logs/error.log". +CustomEntityBundle | Not supported | ### Custom Code @@ -85,22 +72,12 @@ For now, the custom code migration is not automated. Our plan is to enrich Transporteo with a step by step assistant to help you updating your custom code. -## Installation - -### System requirements +### Image and asset files -- php7.1 -- php7.1-gmp -- php7.1-mbstring -- php7.1-json -- php7.1-xml -- [composer](https://getcomposer.org/download/) -- a SSH client +If your images and assets are configured on a remote file system, you just have to configure you 2.0 PIM to access them. +If your images and assets are configured to be stored locally, you have to copy them manually into the 2.0 PIM. -And the same requirements as the PIM as you need a PIM installed on your computer ([instructions](https://docs.akeneo.com/latest/install_pim/manual/system_requirements/system_requirements.html)). -As we don't use Elasticsearch in Transporteo, you can install it the way you want. - -### Install the tool and its dependencies +## Installation ```bash $ composer.phar create-project "akeneo/transporteo":"dev-master" @@ -108,12 +85,6 @@ As we don't use Elasticsearch in Transporteo, you can install it the way you wan ## How to use -### Access to remote servers - -If the 1.7 source PIM you will migrate from is installed remotely, you'll be asked to provide a *private SSH key* able to connect to this server. - -### Upgrade! - To launch the tool, run: ```bash @@ -127,14 +98,16 @@ You will have to migrate it following this [upgrade file](./UPGRADE-2.0.md). We plan to automate this part in future release, stay tuned! :) -*Tip: You can define the default responses in the file "src/Infrastructure/Common/config/parameters.yml"* - -## How to contribute +## Documentation -Please, have a look on the [CONTRIBUTING](./.github/CONTRIBUTING.md) page. +- [Requirements](doc/requirements.md) +- [Advance usage](doc/advance-usage.md) +- [Product variants migration](doc/product-variants-migration.md) -## What's next? +## Support & contribution -We will continuously improve this tool, you can follow our plans [here](https://github.com/akeneo/transporteo/projects/1). +Be aware that this tool is only supported in **best effort** by our team. +If you find an issue or want to ask for an improvement, do not hesitate to open a Github issue on this repository. -You can also have a look on the [changelog](./CHANGELOG.md). +All contributions are of course very welcomed! So do not hesitate to help us build an even better migration tool. We'd love that. +You can have a look to the [Contributing](./.github/CONTRIBUTING.md) page. diff --git a/doc/advance-usage.md b/doc/advance-usage.md new file mode 100644 index 0000000..84894a2 --- /dev/null +++ b/doc/advance-usage.md @@ -0,0 +1,129 @@ +# Advance usage + +## Configuration + +In order to avoid answering questions when starting the migration, you can define the default answsers in the [configuration parameters file](../src/Infrastructure/Common/config/parameters.yml) + +## Migration steps + +Transporteo uses [Symfony workflow](https://github.com/symfony/workflow) to define each step of the migration. You can edit the [workflow configuration file](../src/Infrastructure/Common/config/transporteo_state_machine.yml) to move, add, or remove some steps. Be aware that certain steps are mandatory, and that their orders are sometimes important. + +The most common reason to do that would be to want to migrate only structural data without products. In this case you'll have to remove the steps `destination_pim_product_migration` and `destination_pim_product_variation_migration` because the second step can't be performed without the first one. + +Below is an example of how to remove the steps of products migration: + +```yaml + workflows: + transporteo: + type: 'state_machine' + audit_trail: + enabled: false + marking_store: + type: 'single_state' + arguments: + - 'currentState' + supports: + - 'Akeneo\PimMigration\Domain\TransporteoStateMachine' + places: + - 'ready' + - 'source_pim_location_guessed' + - 'source_pim_configured' + - 'source_pim_api_configured' + - 'source_pim_detected' + - 'destination_pim_location_guessed' + - 'destination_pim_downloaded' + - 'destination_pim_pre_configured' + - 'destination_pim_configured' + - 'destination_pim_api_configured' + - 'destination_pim_detected' + - 'destination_pim_requirements_checked' + - 'destination_pim_system_requirements_installed' + - 'destination_pim_file_database_migrated' + - 'destination_pim_structure_migrated' + - 'destination_pim_family_migrated' + - 'destination_pim_system_migrated' + - 'destination_pim_job_migrated' + - 'destination_pim_group_migrated' + - 'destination_pim_extra_data_migrated' + - 'destination_pim_enterprise_edition_data_migrated' + - 'destination_pim_reference_data_migrated' +# - 'destination_pim_product_migrated' +# - 'destination_pim_product_variation_migrated' + - 'migration_finished' + transitions: + ask_source_pim_location: + from: 'ready' + to: 'source_pim_location_guessed' + local_source_pim_configuration: + from: 'source_pim_location_guessed' + to: 'source_pim_configured' + distant_source_pim_configuration: + from: 'source_pim_location_guessed' + to: 'source_pim_configured' + source_pim_api_configuration: + from: 'source_pim_configured' + to: 'source_pim_api_configured' + source_pim_detection: + from: 'source_pim_api_configured' + to: 'source_pim_detected' + ask_destination_pim_location: + from: 'source_pim_detected' + to: 'destination_pim_location_guessed' + download_destination_pim: + from: 'destination_pim_location_guessed' + to: 'destination_pim_downloaded' + destination_pim_pre_configuration: + from: 'destination_pim_downloaded' + to: 'destination_pim_pre_configured' + destination_pim_configuration: + from: ['destination_pim_downloaded', 'destination_pim_pre_configured'] + to: 'destination_pim_configured' + destination_pim_api_configuration: + from: 'destination_pim_configured' + to: 'destination_pim_api_configured' + destination_pim_detection: + from: 'destination_pim_api_configured' + to: 'destination_pim_detected' + destination_pim_check_requirements: + from: 'destination_pim_detected' + to: 'destination_pim_requirements_checked' + local_destination_pim_system_requirements_installation: + from: 'destination_pim_requirements_checked' + to: 'destination_pim_system_requirements_installed' + destination_pim_file_database_migration: + from: 'destination_pim_system_requirements_installed' + to: 'destination_pim_file_database_migrated' + destination_pim_structure_migration: + from: 'destination_pim_file_database_migrated' + to: 'destination_pim_structure_migrated' + destination_pim_family_migration: + from: 'destination_pim_structure_migrated' + to: 'destination_pim_family_migrated' + destination_pim_system_migration: + from: 'destination_pim_family_migrated' + to: 'destination_pim_system_migrated' + destination_pim_job_migration: + from: 'destination_pim_system_migrated' + to: 'destination_pim_job_migrated' + destination_pim_group_migration: + from: 'destination_pim_job_migrated' + to: 'destination_pim_group_migrated' + destination_pim_extra_data_migration: + from: 'destination_pim_group_migrated' + to: 'destination_pim_extra_data_migrated' + destination_pim_enterprise_edition_data_migration: + from: 'destination_pim_extra_data_migrated' + to: 'destination_pim_enterprise_edition_data_migrated' + destination_pim_reference_data_migration: + from: 'destination_pim_enterprise_edition_data_migrated' + to: 'destination_pim_reference_data_migrated' +# destination_pim_product_migration: +# from: 'destination_pim_reference_data_migrated' +# to: 'destination_pim_product_migrated' +# destination_pim_product_variation_migration: +# from: 'destination_pim_product_migrated' +# to: 'destination_pim_product_variation_migrated' + finish_migration: + from: 'destination_pim_reference_data_migrated' + to: 'migration_finished' +``` diff --git a/doc/product-variants-migration.md b/doc/product-variants-migration.md new file mode 100644 index 0000000..6b49d86 --- /dev/null +++ b/doc/product-variants-migration.md @@ -0,0 +1,28 @@ +# Product variants migration + +If you used variant groups and/or inner variation types (with the paid extension InnerVariationBundle for the Enterprise Edition), or both together, the product migration is done in two steps. At first the products are migrated as they are not taking variants in account. Then in a second step, family variants, product models and product variants are created in the PIM 2.0 to reproduce the variants of the PIM 1.7. + +However , 2.0 PIM is stricter about the use of variations: it enforces to use them in a correct way. +Therefore, some misconception in the use of the variation in 1.7 can prevent the migration of the variants in 2.0. + +Here are the rules that must be respected in order to fully migrate the product variants: + +- All the variants of a product must be of the same family +- A family variant must not have more than 5 axes. +- A variant axis must be one of the following types: + - Simple select + - Reference data simple select + - Metric + - Yes/No + +If a variant group or a inner variation type does not comply with these rules, the concerned products will remain without variant and you will be warned if it occurs. You will have to think about a better modeling for these products and then two options are available: + +1- Create manually the family variants, product models and product variants (directly from the UI, or using the API or imports) in the PIM 2.0 + +2- Fix the invalid variant groups and/or inner variation types in the PIM 1.7 and re-perform the migration. + +You can read this articles to learn more about variants in version 2.0: + +- [What about products with variants?](https://help.akeneo.com/articles/what-about-products-variants.html) +- [Offer choice with variants!](https://medium.com/akeneo-labs/offer-choice-with-variants-8460a82fa36) +- [How Akeneo deals with variants?](https://medium.com/akeneo-labs/how-does-akeneo-deal-with-variants-42bcab83a879) diff --git a/doc/requirements.md b/doc/requirements.md new file mode 100644 index 0000000..f4f80e4 --- /dev/null +++ b/doc/requirements.md @@ -0,0 +1,37 @@ +# Requirements + +## System + +- php7.1 +- php7.1-mbstring +- php7.1-json +- php7.1-xml +- [composer](https://getcomposer.org/download/) +- a SSH client if the 1.7 source PIM you will migrate from is installed remotely. + +And the same requirements as the PIM as you need a PIM installed on your computer ([instructions](https://docs.akeneo.com/latest/install_pim/manual/system_requirements/system_requirements.html)). +As we don't use Elasticsearch in Transporteo, you can install it the way you want. + +## API + +Transporteo uses the API to migrate the products (and variants if there are any). So it has to be functional and well configured on the 1.7 source PIM. + +### Authentication + +You need to have created a pair of client id / secret on the 1.7 source PIM. You can check if a pair of client id / secret already exists with this Symfony command: + +```bash +php app/console pim:oauth-server:list-clients +``` + +And you can create one with: + +```bash +php app/console pim:oauth-server:create-client +``` + +No need to create one on the 2.0 destination PIM. They will all be migrated from the 1.7 source PIM. + +### User + +If the 1.7 source PIM is an enterprise edition, you have to check that the user you'll use has all the Web API permissions, and that he is allowed to view and edit all the products and attributes.