Upgrading extension's data to the latest version
When you develop the next version of your extension, quite often you'll need to provide some procedure to upgrade the data, created by your extension, to the latest version of extension when it is installed.
For example, let's say you developed a payment extension. You released version 1.0, and in this version users are able to create a payment method and specify a "Default payment method" field (like it is in Docdata payment extension). Here's the screenshot from Sana Admin > Setup > Ordering > Payment > Edit payment method page:
You can see on the screenshot that the user specified "VISA; MasterCard; AmericanExpress" as their "Default payment method" field value.
So now you're in development of version 1.1 and in this new version you get to know that your payment provider does not support "MasterCard" as default payment method anymore, for example. And because of this new requirement you need to remove "MasterCard" value if it is present in the "Default payment field" when the user updates their extension to version 1.1.
How it is done in extension add-ons
For each of the data entity type available in the extension framework you can implement an upgrade procedure per each subsequent version of your extension add-on. All you have to do is implement certain predefined upgrade classes and specify pairs of "old" vs. "new" data entity model classes. All this is explained below.
There are seven kinds of upgrade in your extensions:
- Add-on's configuration
- Content block to configuration
- Content block data
- Data records
- Key-value data records
- Payment method settings
- Shipping method settings
Below is a quick reminder of what these entities are and references to the related articles on now they are used.
Extension add-on's configuration
This piece of data is common to any extension add-on. Each add-on may have its configuration and when you develop a new version of add-on you may want to change some data in its configuration. See how to provide configuration in details in configuration guide.
Content block to configuration
If you develop a content block add-on, it will store content blocks in content pages, product pages or other pages in Sana Commerce Cloud, depending where it is used. Content blocks data in those pages can be upgraded to extension add-on configuration. See content block add-on development guide if you're unfamiliar with this extension add-on type.
Content block data
If you develop a content block add-on, it will store content blocks in flexi-pages, product pages or other pages in Sana Commerce Cloud, depending where it is used. Content blocks in those pages can be upgraded too from within extension. See content block add-on development guide if you're unfamiliar with this extension add-on type.
Data records
If you're using client-side in your extension to store your data, you may need to implement upgrades for your data records, created in previous versions of the add-on.
Key-value data records
If you're using key-value data records in your extension to store your data, you may need to implement upgrades for your data records, created in previous versions of the add-on.
Payment method settings
When you develop payment extension add-on you may provide custom settings for payment methods in your add-on. This data can also be upgraded in extension. See how to implement payment method settings in the payment method settings guide.
Shipping method settings
Same as above, in shipping extension add-on you may provide custom settings for shipping methods. Likewise, these settings can be upgraded. Read shipping method settings guide if you want to know more how to implement the settings in your shipping add-on.
The flow
Sana Commerce Cloud takes most of the responsibility for running the upgrades. All the extension add-on needs to do is just provide upgrade implementation per each version of the add-on. See how Sana Commerce Cloud executes the upgrade flow internally and how it cascades upgrades through several subsequent versions.
Implementing upgrades
Now that we went through theoretical stuff let's finally start with some practical example. Next step is the actual extension data upgrade implementation: