Implementing upgrades

Now let's talk about how we actually implement data upgrades in extension add-ons.

In short, the path to follow looks something like this:

• Have an 'Upgrades' folder where you will put your upgrades' code in the extension add-on's project.
• Make sure you have a sub-folder in the 'Upgrades' folder for the previous version, e.g. 'v1.0.0'.
  • Put your old model(s) class(es) to this folder.
• Create a new sub-folder in the 'Upgrades' folder for the new version, e.g. 'v1.0.1'.
  • Put your new model(s) class(es) to this folder.
  • Implement an upgrade class specific to the type of data you're upgrading:
    • ConfigurationUpgrade class for extension configuration upgrade;
    • ContentBlockToConfigurationUpgrade class for upgrading content block data to configuration data;
    • ContentBlockUpgrade class for content block data upgrade;
    • DataRecordsUpgrade class for upgrading client-side API data records.
    • KeyValueDataUpgrade class for upgrading key-value data records.
    • PaymentMethodSettingsUpgrade class for upgrading payment method settings;
    • ShippingMethodSettingsUpgrade class for upgrading shipping method settings;

Now let's go through details of these steps.

Folder structure

We'll use a generic extension add-on as our example. Here's how it looks before we start implementing upgrades:

It does not matter which type of extension add-on you're implementing, be it payment, shipping, content block or whatever else, the steps are basically the same.

At the begining we don't have any upgrades so we create 'Upgrades' folder in a root folder of "Sana.Extensions.Docdata" project. As soon as our add-on might have a lot of upgrades in future we keep classes for upgrades separately in this folder.

Important

Do not delete old upgrades.

We recommend to create sub-folders using version numbering (e.g. 'v1.0'), it helps to keep structure of the upgrades.

First step is to create the initial folder, where we will keep model(s) from the add-on's previous version. In our case, current version is '1.0.1' and previous version was '1.0.0', so let's create a 'v1.0.0' folder first:

In this folder we will place our 'old' model(s), which we will show a bit later.

Now let's create a sub-folder for the current version, which is 'v1.0.1':

We recommend to use this approach for organizing upgrades in your extension.

Upgrading configuration

Any extension add-on may have a configuration model class implemented. If your configuration data changed between versions, then follow the steps needed to implement extension configuration upgrade:

Continue to configuration upgrades

Upgrading content block to configuration

If you have a content block add-on implemented and you need to provide upgrades for the content block data to move settings into configuration for security purposes, you can follow the steps below to get to know how it is to upgrade:

Continue to content block to configuration upgrades

Upgrading content block

When you implement a content block add-on, you create a content block model class too, which may need an upgrade to be implemented for the content block data. The steps to implement content block upgrade can be found in the following tutorial:

Continue to content block upgrades

Upgrading data records

Any extension add-on that has custom views for Sana Admin or the Webstore may also use client-side API. This allows you to store any custom data in the database from client-side. You can also implement upgrades for the data records, which is described in the next tutorial:

Continue to client-side API data records upgrades

Upgrading key-value data records

Any add-on may need to save some data in add-on code via key-value data records. You can also implement upgrades for the key-value data records, which is described in the next tutorial:

Continue to key-value data records upgrades

Upgrading payment method settings

When you implement a payment extension you may create a payment method settings model class which will serve as the model of your payment method's settings data. If this data changes between versions, then you'll need to provide an upgrade for it. Follow the steps in payment method upgrade tutorial to implement it:

Continue to payment method settings upgrades

Upgrading shipping method settings

Similar to payment extensions, when you implement a shipping extension you may create a shipping method settings model class which will serve as the model of your shipping method's settings data. The steps to implement shipping method settings upgrade are described in the following tutorial:

Continue to shipping method settings upgrades

What if there is nothing to upgrade?

It may be the case that you release a new version of your extension add-on and there is nothing to upgrade between the versions. In such case you can simply skip this version in your folder structure. For example:

You can see that on the screenshot we have 'v1.0.0' and 'v1.0.1' folders and then 'v1.0.5' folder - this is how we can skip implementing upgrades for versions where there is nothing to upgrade. So in such example we only have 'v1.0.0 to v1.0.1' upgrade and 'v1.0.1 to v1.0.5' upgrade.