Sitecore Experience Commerce 9 – Versioning

With the release of Sitecore Experience Commerce 9.0.2, we now have rich extensible versioning functionality built into the commerce engine. This works in a similar flow to versioning items, e.g. the existing published version can’t be changed, to amend an entity’s details you need to create a new version which can then contain your changes.

This has some great benefits as it allows you to now make offline edits to entities that you can push live when you’re ready, for example making changes to an entity  over a couple of days until you’re happy and want to push the changes out to the storefront. It also gives you a history of the changes on the entity so you can see which version an edit was made in.

There are some differences to how versioning of Commerce entities functions compared with versioning of content items, and that mostly revolves around the configuration of the functionality. By default versioning is not enabled for entities, you can then choose the entities that you want to enable it for by type. Out of the box in 9.0.2 you will see that versioning has been enabled for Catalogs, Categories & Sellable Items. So let’s take a look at how it works.

Viewing a published entity

When you load up an entity which has versioning enabled in 9.0.2 one of first things you’ll notice is the new Entity Versions panel, as you can see here:

In this example you can see that the entity we’re viewing has a single version that has been published i.e. no more edits can be made to that version. If we take a look at one of the other panels then you notice that all of the edit buttons are now greyed out:

In order to make edits to this entity we need to create a new version which will contain our edits.

Creating a new version

If you scroll up to the top of the entity and the Summary section, then you create a new version using the drop menu on the right, in here you’ll see the new “Add Entity Version” option seen below:

We get a prompt confirming that we want to create a new version. Once we accept this then the new version will be created. The page refreshes and we get a message at the top of the window informing us that “A newer version exists”, this is because we’re still viewing the older published version not the version we can edit. The final thing we need to do to be able to edit the entity is to view the latest version, and to do this we again return to the Entity Versions panel, and then click on the link to the latest version.

Once we do this, the entity’s contents will update and all of the edit buttons that were disabled previously will be enabled once more, allowing us to make the required changes to the entity’s data. Once you’re happy with the changes you can then use the drop menu on the Summary panel to accept the changes and push the entity through workflow. For more information on the new workflow features in 9.0.2, you can read my other post here.

How to enable versioning for other entities

So that’s given you a good walkthrough of how the versioning functionality works out of the box, but as I mentioned at the start of the post it’s also extensible so you can choose what entities you want to have versioning enabled, even enabling it for your own custom entities.

If you take a look in the PlugIn.Versioning.PolicySet-1.0.0.json configuration file that is created with Experience Commerce 9.0.2, you will see multiple instances of the VersioningPolicy. Each instance of this policy applies versioning to a specific type of CommerceEntity in the system. As mentioned above you should see lines for Catalog, Category & SellableItems. So, if you want to enable versioning for your custom CommerceEntity, all you need to do is add your own instance of the VersioningPolicy referencing your customer type e.g.

  "$type": "Sitecore.Commerce.Plugin.EntityVersions.VersioningPolicy, Sitecore.Commerce.Plugin.EntityVersions",
  "TypeFullName": "<<YOUR CUSTOM TYPE>>"

After you add the record for your custom type, you Bootstrap (for more information on Bootstrapping check out our DevOps guide) these changes into the database and you’re done, your custom type will then have versioning enabled, as easy as that! .

Under the hood.

You may have noticed that Catalogs, Categories & Sellable Items are all versioned by default in 9.0.2, but not Variants. The reason for this is that currently you can only version Commerce Entities and not Components, this is because these objects are stored differently under the hood. If you look into the SharedEnvironments database you’ll see that any Commerce Entities which are created all get stored as individual discrete records in the database, whereas components like the ItemVariationComponent aren’t.  Instead they’re stored within the Commerce Entity that contains them. If you take a look at this visual representation of the JSON for a single Sellable Item then you can see the Variants are being stored in the Components array:

Now when you create a new version of an entity the entire entity is duplicated, including all of the Components contained within it. So that means you do get some of the versioning functionality provided for you, e.g. you can go back to previous versions and you’ll be able to see what data was in the Components. However, what you don’t get is the editor locking functionality seen above. Something to bear in mind when you start to use this feature.