Sitecore commerce – Adding and setting new fields on the cart. An end to end example, from UI to API.

The following is an end to end example of how to create, set and use new fields within custom logic on the cart in Sitecore commerce.

The same pattern presented here can be used to set new fields on any entity in the commerce ASP.net core engine.

The example is based on the following business case, a cart needs to be flagged as belonging to a VIP customer and a 20% discount must be given on the subtotal of the cart if the flag is true. If the flag is false no VIP discount is given.

In this example, we will be modifying the Sitecore commerce engine SDK and the Sitecore commerce reference storefront. If you would like to use the retail demo site (Habitat\Helix) the steps will be exactly the same as only the “manager” classes are changed on the front end.

We will be adding our custom code for the commerce engine to the existing “adventure works” plugin. You can use your own plugin, however, I suggest you get the example working with the standard example plugin first then move and rename things as necessary later on.

At a high level, we will be setting the new field on the cart by using a new command created within the commerce engine API. A new pipeline handler will be created within Commerce connect that will execute the new command when a cart line is added in the storefront. The new field will be set on the front end by modifying the managers within the reference storefront code.

Step 1 : Modify the Commerce engine

The Sitecore commerce engine is modified using the SDK. Refer to developers guide for a basic run through here. You can download it here.

Open the main solution “Customer.Sample.Solution.sln” from the root of the SDK and make the following changes…

Add the following to the “Sitecore.Commerce.Plugin.AdventureWorks” project.

  • Add a new component, this component will be responsible for the definition of the new flag “ApplyVIPPricing” on the cart header.
      1. Add a new class named “CartVIPStatusComponent” to a folder named “Components”.
      2. Copy the following code into the class…

  • Add a new command, the command will be responsible for executing the code that sets the new field on the cart header.
      1. Add a new class named “SetCartVIPStatusCommand” to a folder named “Commands”.
      2. Copy the following code into the class…

  • Add a new command controller, the command controller will be responsible for executing the command. This is the route and is what is exposed to the outside world via the API.
      1. Add a new class named “CommandsController” to a folder named “Controller”
      2. Copy the following code into the class

  • Add a new pipeline block, this block is responsible for executing the logic to calculate the new adjustment (VIP discount) based on the flag that has been set on the header. It will run each time a cart is calculated.
      1. Add a new class named “CalculateCartVIPBlock” to a folder named “Pipelines\Blocks”
      2. Copy the following code into the class

  • Add a new pipeline block, this block is responsible for registering the route for the new command.
      1. Add a new class named “ConfigureServiceApiBlock” to a folder named “Pipelines\Blocks”.
      2. Copy the following code into the class

  • Modify the existing classes named “ConfigureSitecore” and “ServiceCollectionExtensions”, these classes are responsible for registering all the custom code with the engine.
      1. Paste or merge the following code into the “ConfigureSitecore” class.

      1. Paste or merge the following code into the “ServiceCollectionExtensions” class.

Build the modified commerce engine and the start solution. The default behavior is for a IIS express site to start on port 5000.  Refer to the “Test the solution” section below to validate that these steps have been followed correctly.

Step 2 : Rebuild the proxy

Commerce connect uses a service proxy to communicate with the commerce engine. We must rebuild the proxy to include the new command we just added to the engine.

Open the proxy solution “Sitecore.Commerce.ServiceProxy.sln” that is part of the SDK, it is located in the root of the SDK folder.

For example…

“C:\Development\Sitecore.Commerce.SDK.1.1.819\Sitecore.Commerce.ServiceProxy.sln”

To rebuild the proxy follow these steps

  1. Open the file named “CommerceApiClient.tt” make any small change to the file and undo it e.g. a new line at the top of the file and remove it.
  2. Save the file, you will be prompted that the code will be rebuilt. Select “OK. If you have any issues regarding the “Microsoft.OData.XXX.dll” not being found you can copy them from the Sitecore directory into the location mentioned in the error.
  3. Once the proxy has successfully been rebuilt copy the resultant assembly into your Sitecore “Bin” folder.

You will now reference this new proxy from a new pipeline handler.

Step 3 : Call the new code from commerce connect

Next, we will create a custom pipeline handler for the “AddCartLine” pipeline and register it using Sitecore configuration. Our pipeline handler will execute our custom command in the engine before each call to the to add a line.

    1. Open the source code for the reference store front, the retail demo site or your custom solution and add a new Class library project called “Sitecore.Commerce.Examples”.
    2. Add the references below from either your Sitecore Bin directory (Not recommended), nuget server or other location. Note : The proxy assembly must be the new one we built earlier.
      VIP example references
    1. Add a new class named “SetCustomFieldsByCommand” under a folder named “Pipelines\Carts”.
    2. Copy the following code into the new class…

    1. Add a new xml file named “ZZZ.Sitecore.Commerce.Examples.config” to a folder named “Configs”.
    2. Copy the following markup into the new config file.

  1. Build the new project and copy the resultant assembly into your Sitecore Bin folder.
  2. Copy the .config file into the Sitecore App_Config folder under “…\Include\Y.Commerce.Engine”. For example… “C:\inetpub\sc821u3\Website\App_Config\Include\Y.Commerce.Engine\ZZZ.Sitecore.Commerce.Examples.config”

The config file will register our new pipeline handler to run before the standard handler that adds lines to the cart. In a real word example you could call the new the command from any pipeline that suites your needs.

Step 3: Modify the front end code

The final step is to set the new field named “applyVIPPricing” on the cart header from the site implementation itself. This value will then flow through commerce connect and be set on the cart via the API. The custom logic we created earlier will then be triggered within the engine if the new field is true.

This is done using the “Properties” collection on the request.

    1. Open the reference storefront solution
    2. In the “Commerce.Storefront” project open the “CartManager” class.
    3. Find the “AddLineItemsToCart” method and replace it or merge it with following code.

  1. Deploy the customized assembly to your Sitecore Bin folder.

The entire project is located here.

Test the example

Test the commerce engine changes first by using postman to call the new command following these steps :-

  1. Open postman
  2. Import the all the postman examples from “Postman” folder in the Commerce engine SDK folder. For example, “C:\Development\Sitecore.Commerce.SDK.1.1.819\Postman”. Refer to the documentation on the developers guide located on the dev.sitecore.net located here
  3. Import the “SetCartVIPStatus” postman sample located in the “Postman” folder of the “Sitecore.Commerce.Examples” project within the source code for this example.
  4. Execute the “Get Cart” call in the “CartAPISamples” folder. This will create a cart named “Cart01”.
  5. Execute the new “Set cart VIP status” call (Commerce examples folder). This will set the “applyVIPPricing” flag on the cart “Cart01”.
  6. Execute the “Add Mira laptop” call. This will add a line to the cart, run the new logic when the cart is calculated and create a new adjustment of 20% on the cart “Cart01”.
  7. Execute the “Get Cart” call again, you should see the new adjustment values in the response. For example…VIP postman test

Test the pipeline and front end change simply by opening the reference storefront and adding a line to the cart. If the solution is working correctly the Total for the cart should be discounted by 20%.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s