This time I would like to share some thoughts on the topic of how to extend your commerce entites.
If you are already working with Sitecore XC you will most probably know, that commerce entities in general are extended via components. So if e.g. your sellable item entity needs more properties, like nutrients or allergies for food products you would just create a new component and “attach” it to the sellable item.
From version 9 on Sitecore introduced a new application Composer, with which it should be very easy to extend all kind of OOTB commerce entities. If you would like to know more about Composer in general, I would recommend you to read one of my articles about Composer. In general with this Composer application you can create new custom views with all kind of custom properties. You can then link that new view to any of OOTB entities like sellable item, customer, catalog, category etc. And if you now e.g. use Merchandise tool to see the sellable item and edit it, you will directly also recognize all the new custom views and properties created via Composer and linked to that entity. So without writing a single line of code you are able to completely customize and individualize all you entities and maintain them directly.
So the question at this point would be:
Why should you not use that fancy feature?
The answer of course is not so easy. Let us have a closer look at Composer and how to really work with it in a real world scenario.
Composer in real world
In one of my Sitecore XC projects, we were faced the task to extend standard sellable item with quiet a lot new properties. The version we started was at this time was 9.1. And because of that, the first approach which came into my mind was to use Composer. I already knew about one disadvantage of using Composer, which I directly wanted to work around. If you create a new composer template within e.g. your local instance, it might work perfectly fine. But the trouble already starts, when you try, to bring that newly created composer template to other DEV instances, testing or production. There is currently no OOTB way of deploying such templates to other environments. You can just create these templates and link them to other entities. This would later on lead to massively different instances, which is not track- or maintainable anymore. Because of that, the community already thought about some workarounds to overcome that issue, so that compser templates are deployable again.
- Code First Approach: https://websterian.com/2018/08/10/sitecore-commerce-9-moving-entity-composer-templates-between-environments-a-code-first-approach/
- JSON Based Appraoch: https://hachweb.wordpress.com/2018/11/30/sitecore-xc-9-0-2-full-example-of-how-to-sync-composer-generated-templates-between-environments/
For my solution I was building, I decided to use Code First Approach. Once you created a new template, you would, as usual, check in this file into your repository, where it is getting versioned and shared among other DEVs instances and later on in release management also on other environments like TEST or PROD fully automated.
And at first everything went well so far. I was able to programmatically create all of my new custom views and link them correctly to my sellable item entities. I was also able see and edit these new views and properties in entity view. OK, to be 100% honest, I was able to create and maintain all of my custom views for sellable item entity. But what about variants of sellable items? You might now, that variants of sellable items are no entities. Variants themselves are handled as components, which extend standard sellable items. If your now try to extend properties of sellable item variants, instead of sellable item, you will quickly find out, that this is right now not possible at all. At the moment, you just can link your composer templates to entities.
This means, that you cannot use composer to extend sellable item variants. To extend sellable item variants, you have to use plain, “old” components and do it on your own.
Next step was now to import product data from some web service to Sitecore. And here the odyssey started. I struggled a lot with adding data to composer generated custom views, but because if some reasons. For some of my issues I also created Sitecore support ticket. And one of the ticket also pointed out to be a bug in the system. But let me explain in detail, so you don’t have to go through all of that on your own.
It all started with the question of, how to access programmatically composer generated custom views. Of course Sitecore XC offers calls for creating, editing and retrieving sellable items in general. Now, based on the assumption, we correctly created or retrieved our sellable item entity, where do we find our custom views, so we can edit them? unfortunately the answer is not that easy, so I just provide you some code, which I wrote for my case, which does the job.
- Grab the sellable item
- Use GetEntityViewCommand to grab sellable items entity view
- Find the view you would like to edit
- Grab the EditView of that specific view
- Iterate through all the properties you want to edit and edit them
- Use DoActionCommand to save all the changes
As you can already see, such an approach is more complicated than you would usually edit a sellable item with components. In addition with more and more custom views you edit, the performance of the overall import process is getting worse and worse. And not only that. I encountered the strange behavior, that from time to time the properties were not correctly added or edited for the custom views. Some times it worked and some times it just did nothing. But OK. For now I accepted that, and created a support ticket to be sure, it is not a bug or something like that.
And after implementing the basic code for importing everything, I started testing various scenarios like, edit existing item, create item and add data, delete the item and recreate it, and also delete composer template and recreate that, to be sure, that all these scenarios work in other environments without any problems. But while testing around, I encountered another strange behavior. The situation was, that I created a sellable item with custom views. I added some data to that item and filled the custom view. Now I wanted to delete the composer template, recreate it and import the data again to the sellable item. The problem now was, even after deleting the composer template, the filled custom views were still present on the sellable item. And even worse, after recreating the composer template again, the custom view was present on the sellable item twice. One time filled from earlier test and one time new fresh empty one. I was not able to remove the custom view, until I completely deleted the current sellable item and recreate it. After doing that, it again just had all the custom views just one time. Because that really was a strange issue, I also created a support ticket for that behavior.
Support Tickets with topic Compser
- Out of support scope – Properly fill composer properties programmatically
- 278078 – Sitecore XC: Composer generated views are displayed multiple times on sellable items
To be completely honest, I created some more support tickets, than these two. But all the other tickets had some other issues while implementing an importer. And of course in future blog post I will keep you informed about newly found and registered bugs. For now we just have a look at these two tickets about composer. The first one, was unfortunately out of scope as part of Sitecore support. The problem was, that basically the code works, but just did not add values from time to time. To resolve that issue, I was asked to directly contact regional Sitecore representative to get help from the Professional Services team.
Let’s have a look in the meantime at the other issue. After some discussions the issue was registered as bug under the reference number 278078. So right now, you might get trouble when you use composer templates on your entities, fill them, delete the templates and recreate them. And right now there is no easy way of overcoming that issue, other than rewriting some really basic composer code.
So while struggling with all these kinds of issues, I was able to talk also with an architect from Sitecore. You remember, that this was the advice of Sitecore support I followed now. After a short discussion it pointed out, that composer might not be the best choice considering the current situation and how I use it.
And I have to admit, that I fully share that opinion after I really tried to integrate that new feature into the development workflow. It is still a quiet new feature with a few weaknesses, which have to be overcome first to unleash it’s full potential. But if we do not use Composer to extend all our sellable items, the question now is:
What can we use instead of using Composer?
Back to the roots – Why not using just components directly?
You really don’t have to use Composer to extend any kind of commerce entity. Before Composer was introduced, there was a pretty standard way, of how you can extend all kind of commerce entities on your own. You just created a new component, with all your properties you wanted the entity to have.
Sitecore also has some helper functionality OOTB, with which you can easily get, create and set custom components on entities to maintain your custom components.
In the end, after getting the component and setting your properties, you just have to persist the entity again to the database, and that’s it.
So for an importer process, it’s also nothing more, than this. Instead of finding custom, edit views, adding properties there and calling a magic DoActionCommand in the background for each view you changed, you just grab the sellable item, grab the component with the OOTB helper, set the properties and in the end, as usual, persist entity. And I guess this might be the plainest, easiest and most performant way of editing custom properties of your entities.
I already tested this approach with 8 custom components with more than 80 custom properties, which extended the standard sellable item entity, and the importer was definitely not that slowly, than it was, when using the composer based approach.
But I would say, we have one big disadvantage of using this approach. When using Composer to create templates, these templates and respective the custom views, which can be seen in the screenshot above, are directly visible and editable on the linked entities. This benefit, we do not have, when creating and adding components directly to our entities. To see and edit the new properties of our entities, we have to implement some further logic, which extends the standard entity view, in our case the sellable item entity view, with all our new components. And with exact this way we also can extend our sellable item variants. If you would like to know more, about how to extend Business Tools, and in this case entity views to see and edit custom properties, I would strongly recommend you, to read this article of me, where I describe in detail the process with the example of creating and extending the cart entity view.
So of course this produces a bit more work to get everything working, but I guess at the moment, for this scenario, I was faced to, it is still the better approach, because in the end, if something does not work as expected, you can completely customize or work around everything.
You might now remember the code from the beginning, where I showed, how to edit custom view of sellable item. I will now show you, how the code changed now in importer.
So you see, that this piece of code definitely became much easier, than before. Instead of duzend of lines of code for preparation and retrieval it is more or less just one line of code for retrieval and X lines for X properties to change.
Within this article you learned, that there are various ways of extending Sitecore XC entities with custom properties. You saw, that the newly introduced Composer application might look cool and in general has a lot of potential to make the life of authors and developers much easier. But right at the moment you clearly have to weigh well, if Composer is the right tool for your business needs and requirements. If not, don’t be afraid of using plain, old components directly. It might lead to more work in the beginning, but in the end it might safe you a lot more time.