Skip to content

Admin v4 upgrade guide

This document outlines the steps to upgrade from Admin v3 to Admin v4. For an overview of the new features and changes between the versions, refer to the Admin API v4 specification.

Please note that depending on your setup and requirements, the steps may vary during the upgrade process. Should you need any assistance during the upgrade process, please contact Voyado Support. Let's get started!

Prerequisites

Before proceeding with the upgrade, ensure that the following prerequisites are met.

  • Notice to and approval by Voyado have been provided for the upgrade.
  • There is a currently live integration in production using Admin API v3 for imports.
  • Every unique product group, product, variant, and content key serves as a consistent identifier for the same item across different markets. That is, a single identifier must not be used for different products in two markets.
  • Market identifiers and locales are kept identical to the ones used for v3 during the upgrade process.

Rollback and recovery

It is possible to downgrade to Admin v3 at any point during the upgrade process. When doing so, all v4 import endpoints will start returning 405 response code errors and all v3 import endpoints will start working as previously.

To downgrade to v3, perform a full v3 import admin/v3/import/data with the query parameter downgrade=true.

Upgrade process

There are two approaches to upgrading the data feed, one basic and one slightly more advanced. The one most suitable for you depends on the number of import sources and your import uptime requirements. The main difference is that the advanced upgrade will have a fully uninterrupted partial import flow during the upgrade process.

The overview of the processes explains the main components of the upgrade process and the step by step sections provides and example of how to roll it out safely, including the usage of a test environment and some utility features provided by Voyado. Depending on how fast rollouts are made and what levels of precautions are needed for your setup, all steps are not needed as long as the tasks in the overview are fulfilled.

  • No v4 configuration imports should be made during the upgrade process.
  • For other Admin endpoints than those for the data feed, update the version in the request path.

Basic data feed upgrade

When

If only full imports are made or all imports are made from a single system or if temporary halts in the partial update flow are acceptable during the import process, the basic upgrade flow is recommended.

Overview

The basic upgrade process fundamentally consists of these tasks:

  1. Migrate the v3 full import to the v4 catalog format for replacing the catalog and ensure it is imported successfully.
  2. Migrate all v3 partial and attribute modification imports to the v4 catalog format for updating the catalog and ensure they are imported successfully.
  3. Ensure the scheduling of future updates use v4 and that v3 updates are turned off.

Step by step

The following steps are recommended to be performed in your test environment, before rolling out or making the same the equivalent changes to production.

  1. Optional Make a full admin v3 export admin/v3/export/data for immediate access in case of a need to roll back.
  2. Optional Use the new endpoint admin/v4/export/upgrade-catalog to get an example of how your data roughly should look in the new format for reference.
  3. Optional Import the retrieved file to the new endpoint admin/v4/import/catalog via PUT, and with the query parameter validationOnly=true.
  4. Optional Should you get an error response, please refer to troubleshooting and ensure these errors are resolved in the file you are to generate in step 6.
  5. Modify any automated import retries on import errors to handle 405 response code errors. On 405, do not retry the import.
  6. Generate an import for replacing the catalog according the catalog specification and following the guidelines. The result from this should normally be similar to what you retrieved from step 2.
  7. Import the generated file to the new endpoint admin/v4/import/catalog via PUT. The cluster will now no longer accept v3 data imports.
  8. Should you get an error response, please refer to troubleshooting and ensure these errors are resolved. Repeat this and the previous step until the file is imported successfully.
  9. Validate that the site connected to the cluster behaves as before. No alterations to the Storefront API usage should be necessary.
  10. For partial updates, generate import files for updating the catalog according the catalog specification and following the guidelines.
  11. Import a file produced from the previous step to the new endpoint admin/v4/import/catalog via POST.
  12. Should you get an error response, please refer to troubleshooting and ensure these errors are resolved. Repeat this and the previous step until the file is imported successfully.
  13. Update the code the scheduling of full imports and partial imports to only use v4 imports.
  14. The upgrade is done!

Advanced data feed upgrade

When

The advanced upgrade process is recommended when there are multiple import sources and either of the following conditions are true:

  • It is paramount that there are no interruptions of partial or modification imports during the upgrade process
  • Rolling out releases to your import systems are very time-consuming

Overview

In the advanced upgrade process, your data sources will produce both v3 and v4 import formats simultaneously during a period of time with some of the requests failing. It also differs from the basic flow in that sources for partial updates are rolled out prior to full imports, and that the steps for the test environment and production environment differs slightly.

The advanced upgrade process fundamentally consists of these tasks:

  1. Test environment: Migrate the v3 full import to the v4 catalog format for replacing the catalog and ensure it is imported successfully.
  2. Test environment: Migrate all v3 partial and attribute modification imports to the v4 catalog format for updating the catalog and ensure they are imported successfully.
  3. Production environment: Release all partial and attribute modification sources to produce imports of both v3 and v4 imports. Note: All v4 imports will fail until step 4 is completed.
  4. Production environment: Release import source for full import. The first can be pushed manually if imports are infrequent. Note: All v3 imports will now fail
  5. Ensure the scheduling of future updates only use v4 and that v3 updates are turned off.

Step by step

  1. Test environment: Perform step 1-12 from the basic data feed upgrade.
  2. Test environment: Update all import systems that produce partial imports or attribute modifications to also produce v4 imports
  3. Production environment: Roll out the changes to the import systems that produce partial imports or attribute modifications. Note: All v4 imports will fail on production until later in the upgrade process, this is expected.
  4. Test environment: Update the import systems that produce full updates to also produce v4 imports
  5. Production environment: Roll out the changes to the import system that produce full imports.
  6. Production environment: Wait until the first v4 import has occurred. If full imports are infrequent, optionally trigger a v4 catalog replacement import manually. Note that all v3 imports will now start to fail on production while all v4 imports should succeed, this is expected.
  7. Test environment: Remove v3 imports from all import source systems
  8. Production environment: Roll out removal of v3 imports to all import source systems
  9. The upgrade is done!

Troubleshooting

Apart from the obvious format changes, there are a some new implicit format requirements as well as a few validation bug fixes which are more subtle. This table show-cases some unsanctioned data issues which were possible to import using v3, but now are explicitly forbidden.

Error Description
Product keys must be unique and not reused for different product groups This was previously only an explicit requirement per market. If you receive this error, it can be an indication of that the same product key have been used for different products in different markets. If so, this is a fundamental key constraint that must be resolved.
Variant keys must be unique and not reused for different products This was previously only an explicit requirement per market. If you receive this error, it can be an indication of that the same variant key have been used for different variants in different markets. If so, this is a fundamental key constraint that must be resolved.
Duplicate size values To not have the same size value for different variants within the same product was previously a data requirement according to the documentation, but the validation was erroneous and could not be fixed in v3 due to its breaking change nature. If this occurs, the data needs to be fixed.
Duplicate label values To not have the same label value for different variants within the same product was previously a data requirement according to the documentation, but the validation was erroneous and could not be fixed in v3 due to its breaking change nature. If this occurs, the data needs to be fixed.
Missing common size format Having at least one common size format for all variants within the same product was previously a data requirement according to the documentation, but the validation was erroneous and could not be fixed in v3 due to its breaking change nature. If this occurs, the data needs to be fixed.
Invalid content url Having a valid content url was previously a data requirement according to the documentation, but the validation was erroneous and could not be fixed in v3 due to its breaking change nature. If this occurs, the data needs to be fixed.
Different content types in different markets for same content id This is simply no longer possible to import, and can impact the content selections or filters where content type is used if the content type for the same content id used to differ between different markets.

Additional resources

×
Copyright

This online publication is intellectual property of Voyado Lund AB. Its contents can be duplicated in part or whole, provided that a copyright label is visibly located on each copy and the copy is used in conjunction with the product described within this document.

All information found in these documents has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither Voyado Lund AB nor the authors shall be held liable for possible errors or the consequences thereof.

Software and hardware descriptions cited in these documents might be registered trademarks. All trade names are subject to copyright restrictions and may be registered trademarks. Voyado Lund AB essentially adheres to the manufacturer’s spelling. Names of products and trademarks appearing in this document, with or without specific notation, are likewise subject to trademark and trade protection laws and may thus fall under copyright restrictions.

CLOSE