The release of Sitecore Experience Commerce 8.2.1 last year introduced the entity concept that the new system would be based on and with the release of version 9 this year all of the functionality in the system is now based on this concept. Now this is super-flexible, but until recently if you wanted to extend the definition of any of the entities, for example to add a new field to the Sellable Items, then you would need a developer to write some C# code to achieve this by following the example in this KB article.
This has now changed however, with the release of Experience Commerce (XC) 9.0.2. You no longer need to get a developer involved to achieve this, it’s now possible extend the different entities in the system directly through the Commerce Business Tools. This isn’t just the catalog entities though, you can extend most of the entities stored in the system e.g. Sellable Items, Customers, and Pricing & Promotion entities, using the new Entity Composer included in 9.0.2.
The Entity Composer allows you to build custom data views to contain the properties you want to add to the entity in question. You can then convert this view to a template to be applied to other entities which need the same data to the applied. Let’s take a look at an example of how this works in practice.
Extending the Sellable Item definition
In this example we’re going to extend some of the Sellable Items in the Habitat_Master catalog provided with XC 9 to include some custom data applicable to those products. In this case we’re going to extend the Headphones items with some headphone-specific data. We start off by opening up the Commerce Business Tools and navigating to a headphone item for sale on the site. Once you open it you should see a new Icon is present in the Item’s Summary section. This is where Entity Composer functionality is available.
We click on the first Icon to “Add a child view”, this opens a prompt allowing us to give the Child View a name, and in this case we’ll choose Headphones:
Once you click the tick you will see the section appear in the items definition, though it won’t have any properties yet as we need to add them. We do this by using “Add Property” menu on the new Item section and we’re going to add the following headphone specific properties:
Here the Name column is the identifier that will be used for the record in the database and the Display Name field is the value that will be displayed on the Storefront if needed.
Now with the Type property we want people to be able to specify either Wired or Wireless, however we don’t want users to have to type that each time so we add these two values as Option Constraints. Using the same drop menu we used to create the properties, we instead this time choose “Add selection option constraint” and setup the values as you can see here:
Now we’ve setup the properties we want, we can return to the same drop menu and choose Edit View to populate the properties we just created. The final action we need to do is to turn this into a Template so that is can be assigned to other entities. To do this we again return to the drop menu on the Headphones section and this time we choose to “Make Template” and give it the name Headphones.
Assigning a Template
So we’ve now extended the definition for the headphones item we were editing before, but we need to apply the same changes to the other headphones in the catalog so that the values can be populated for them as well. We’re going to use the new Item Definition concept to achieve this. When you load up the Commerce Business Tools you will see the new Composer section in the main navigation, this is where the Entity Composer views are all managed so if you click on that you will see the Headphones template we just created listed in there.
When you open the Template by clicking on its name you can see the name of the Template and the properties that we created earlier, in-between those sections though we have the Details section where we can assign this template to other entities. You can do this in 3 different ways:
We’re going to use the Item Definitions option this time so we click on the end icon. After that we choose the Habitat_Master catalog, then the Headphones Item Definition.
Now you can navigate to the other Headphones in the catalog and they will all have our new section complete with custom Headphones specific properties ready to be populated.
Getting the Data into Sitecore’s Content Tree
So now we’ve got the data setup correctly in the Commerce Business Tools, the last thing we need to do is also get that data over to Sitecore via the Commerce Data Provider that pulls the catalog data into the Content Tree.
If you load up the Content Editor and look into the Commerce ribbon then you will see a button to Update Data Templates:
Clicking this will force Sitecore to refresh the Commerce data templates that are loaded and pull in any changes you’ve made, including the new views you’ve created. This is usually pretty quick to run and once complete you’ll see the data we added right there in the Content Editor, ready to be used as you would any other Commerce data in the system.
So in this example we extended the definition of the Headphone Sellable Items on the site, but this same process can be followed again and again. Say you wanted to create some custom properties for the TVs for sale on your site with things like Screen Size & Resolution, or maybe you want to extend the Customer entities so you can store users social account details like Twitter handle, or maybe you want to extend your promotions to include some custom properties – well this is all handled in exactly the same way, and most importantly without a developer needing to be involved!
Hi Rob, are these fields also translatable? If I look at the code it doesn't look that way..
Great walk through, Rob. Are there any walkthroughs on Item Definitions? I am having trouble finding them in the UI or in the documentation.