Within this article I would like to deal with some groundwork regarding Sitecore XC. As hopefully all of you know Sitecore XC is an extension to standard Sitecore XP, which enriches Sitecore with a powerful commerce engine. The big question is:
Does everyone of you know how exactly XP and XC are connected, and how you can have influence on this connection?
To answer that question, I would like to give you a general overview of that connection layer, which is called Commerce Connect.
Therefore I would like to start with the standard definition Sitecore gives us within doc.sitecore.net.
“Sitecore Commerce Connect is the Sitecore commerce API for storefront developers and is an integration layer between a front-end webshop solution and a back-end external commerce system. The back-end system can be any e-commerce system for which Commerce Connect connectors have been created by Sitecore or a third-party vendor.”
Now we want to have a look, how this Commerce Connect is integrated within a common commerce scenario with XP and XC components and where we can see that piece of software. For that, let us have a look at the following graphic.
This graphic show a standard architecture overview of a standard Sitecore XC integration. As a base we always have standard Sitecore XP, at this point with related software like, SIF and SxA, which we optionally can use for Sitecore XC. On top of that we have the commerce engine of Sitecore XC. Now highlighted the imported area of the diagram, where we can see the connection of XP and XC. Commerce Connect is installed with the installation of two packages “Sitecore Commerce Connect Core” which installs the basic Commerce Connect module and “Sitecore Commerce Engine Connect” which installs very specific functionality, which is used to implement the connection between Sitecore XP and XC. This package, patches all the general implementations, with concrete implementations for Sitecore XC. Commerce Connect in the end then acts as a middleware with which it is very easy to communicate with the commerce engine via standard and predefined interfaces, pipelines and so on.
Now lets have a look, what we get, when we have installed the Commerce Connect packages. This is especially imported, if you have the need to add, delete or modify something for your custom business needs.
Lets first investigate the items we get. In the content editor we get a new area called “Commerce” as you can see below.
In scenarios, where you connect other external commerce systems to Sitecore XP, this area is even more imported, than in the case, where we integrate Sitecore XC. The most imported sections under the Commerce item are
- Commerce Control Panel
- Commerce Engine Settings
- Commerce Terms
- Shared Settings
- Commerce Engine Settings
Nowadays the section Catalog is not used anymore from the Content Editor, because Sitecore XC has its own tool for handling Commerce Catalogs, the Merchandise Manager. Therefore the Sitecore recommendation is not to use Content Editor anymore for dealing with catalog data.
Within the section Commerce Terms we set all the commerce related texts, which are used within the Sitecore XC Business Tools. Lets have a look how, with the example of adding a custom condition to the Promotion Manager. To add a custom condition it is enough to create a class like seen below.
Within the ConfigureSitecore file just register the new rules and conditions with the following command.
After you did that, you have only one single step left to do. Now you have to go tho the Content Editor under the Commerce Terms section and find, in this case, the area for Conditions. There you add a new Item, which has exactly the same name, than the used in the Attribute EntityIdentifier. Within this Item you now can add your individual text for your new condition. You can also use placeholder for custom input with the syntax [PROPERTYNAME] and a property within you class of type IRuleValue<TYPE>.
If you correctly did that, you can just open the Promotion Manager and the under the conditions list your custom condition with your individual text.
You can see the new condition with its entity name, and if you choose it, choose your custom input, in this case StartHour and EndHour.
I think the sections Shared Settings and Storefronts are quiet self explaining. Within Storefront you create your individual Storefronts for you Sitecore instance and link them to the specific environments, these storefronts should use.
NOTE: Currently there is a bug in the choice of environments. The field for choosing an environment was deleted in the last version, so for every storefront Sitecore always falls back to the standard environment, which is set in the /Y.Commerce.Engine/Sitecore.Commerce.Engine.Connect.config.
To get rid of that, just go to the Storefront template and add the field again to the template
On the left side, we see, how the field should look like, in the example of Sitecore Commerce 8.2.1. On the right side, we see, that the Environment field is gone within Sitecore XC. The logic in the background is still there, so it is enough to manually add that field again to storefront template. Sitecore already registered that as a bug.
Now lets go on to the next stuff, we get after installing Commerce Connect.
As you can see in the graphic above we get a bunch of new config file and within these configs a bunch of new commerce related pipelines. These pipelines are an essential part of Commerce Connect. Within the graphic above you can for demonstration reason see the AddCartLines pipeline. The left graphic shows, what is installed within the standard Commerce Connect packages, from Sitecore Commerce Connect Core. There we only get a standard pipeline with some really basic processors, which in the end only trigger analytics events and handle xDB stuff. The magic we get with a new config file, which we get after installing Sitecore Commerce Engine Connect. The right graphic shows, that the new config file patches the existing pipeline with custom processors, especially e.g with the processor AddCartLines. These patches and processors hold all the business related logic to establish a proper connection to the external commerce system, in this case Sitecore XC. These processors in the end make the rest API calls and communicate with the commerce engine. Both configs together build a fully working and functional pipeline to on the one hand trigger external system logic, and on the other hand track everything within Sitecore XP xDB.
The question now is, how are these pipelines be triggered. The answer comes in the next chapter API.
Last but not least, what I want to mention within my article is the OOTB available API Sitecore Commerce Connect gives us to interact with external commerce systems. From the previous chapter, you already know, that we got a bunch of different pipelines. Now we see, how we can trigger these pipelines from code. Sitecore Commerce Connect is delivered with a various number of so called Service Provider. If you use these service provider from Commerce Connect, in the end the corresponding pipelines are called and executed and you do not have to take care of anything else, just using these service provider correctly.
Above you can see such a service provider call from an implementation of Sitecore Comemrce 8.2.1. As you can see, there is some piece of business logic with grabs the parameter, checks them and builds up the necessary request object for our commerce connect call. Then the commerce connect call, in this case, UpdateCartLines is executed with its request object. As result we get a very specific result object, which holds the information, if the call was successful, if not the error, and the inner object, in this case the modified cart object, which we then can use for our further purposes.
All these Commerce Connect calls are structured in the same way. They have their own request and result object, and only have to be triggered correctly.
Within Sitecore Commerce 8.2.1 we still had to implement our business logic around the commerce connect service provider.
But from Sitecore XC on, we do not have to do that anymore, cause from that time on, Sitecore integrated commerce functionality into the SxA including such implementation for commerce connect service provider.
As you can see in the image below, you can find these implementations in the DLL Sitecore.Commerce.XA.Foundation.Connect.dll und the namespace Sitecore.Commerce.XA.Foundation.Connect.Managers
There you can find the various Managers to interact with Commerce Connect, like CartManager, CatalogManager etc.
If you have a closer look at on of these Managers like the ICartManager, you can see all the available implementations, which can be used within your Sitecore XP solution, without the need to write a single line of code.
Note: If you reflector through the implementations, you will notice, that some of the functionalities of Commerce Connect are not implemented right now. These functionalities, then would have to be implemented by you on XP and if necessary on XC side, to be fully working.
Within this article you learned how Sitecore XP and XC are connected. You saw the different parts like, items, pipelines and API you get with the installed middleware. And especially how you can influence the standard behavior and where you have to make your changes for your custom business needs.