CategoryCommerce

Elements of a Sitecore Commerce Plugin project template

In my previous post we saw the first step to create a new plugin by adding a new plugin project to the solution, restoring the correct binaries and reference new plugin to the Engine project.

In this post I will share what comes with the Plugin project template.

Sitecore Commerce Plugin project template creates folders and classes which helps to quick start creating a plugin, lets see what are these files –

1. Commands

To my understanding command is unit of work to perform set of actions. Commands allows to execute a pipeline and blocks within a transaction scope. Create a custom command by inheriting from CommerceCommand class. Use PerformTransaction method to run a pipeline in a transaction scope.

2. Components

If you want to extend existing or custom entities, use component. Component has attributes that support entities.

3. Controllers –

Controllers expose commerce functionality implemented in plugins. They are the api endpoints. Sitecore Commerce has various Controller type- Entity, Api, Devops and Command. Create your own controllers by inheriting from CommerceController

4. Entities-

They are the persistable unit and represent the business concept. Inherited from the CommerceEntity they has a unique identifier that helps to retrieve the entity by using a Entity controller type.

5. Models –

They are the POCO classes that are reusable in entities and components. Can be used to present data as part of command response .

6. Pipelines – They do the heavy lifting in plugin by making it possible to define the extensible behavior. Create your own pipeline and add blocks you want to execute to implement your business logic. Blocks within pipelines execute in a sequence they are registered.

7. Policies

Policies defines behavior for the functionality provided by the plugin. Its is recommended to not extend or inherit out-of-box plugins instead create your own. Plugins can be changed or created new by updating the JSON files provided in environment folder of the various roles site.

ConfigureSitecore

ConfigureSitecore class helps to register the pipeline and block definitions that a plugin defines. You can create a new plugin and AddPipeline or extend the existing pipeline by adding a block After or Before any existing blocks. ConfigureSitecore class registers pipelines every time engine loads. You can also register commands or register your custom class in this class.

ConfigureServiceApiBlock

This registers customer entities, components and controller action with ODATA model. It allows to these elements to be used when a REST API call is made and available when generating a proxy.

Enable Catalog search in business tool for Sitecore 9.1 Commerce environments

Sitecore Commerce indexes Catalogs, Categories and SellableItems to help search items in Business tools. The settings for the Search can be found in PlugIn.Search.PolicySet-1.0.0.json

These indexes has a search scope, for searching catalog and related items by default the scope is “xc910CatalogItemsScope”

So in SOLR indexed items related to catalogs are kept in core – “xc910CatalogItemsScope”

By default Sitecore will index only Habitat Environment in Sitecore Commerce 9.1. If you want to index your custom environment or AdventureWorks environment, follow these steps-

  • Open Sitecore.Commerce.Engine.Connectors.Index.Common.config file. This should be in CM Y.Commerce.Engine folder
  • In this instance for Adventureworks add “AdventureWorksAuthoring” in Environemnts element for Master Index and “AdventureWorksShops” for Web Index
  • Open Postman and Run – Full Index Minion Catalog Items
  • Check if the items are indexed correctly in SOLR.
  • Search the same keyword in Business tool for AdeventureWorks environment

First Steps | Sitecore Commerce Development | Create a Custom Plugin

In my last post, I have described the steps to set up the Sitecore Commerce development environment. In this post, I will describe how to create a custom plugin in Sitecore Commerce. I was working on version 9.3 but these steps should work with all versions of 9 series.

Sitecore Commerce provides an extensible framework which can be extended using plugins. A plugin is an independently publishable extension to the Sitecore Commerce Engine. Generally, you will find the following contained in a plugin and are used to extend the platform.

  • Entities
  • Components
  • Entity Views
  • Pipeline
  • Policies etc.

You can extend the platform or add more features using the plugins. Let’s get started and look into the steps to create a new plugin in Sitecore Commerce 9.3. If you have already set up your commerce development environment, please skip to step 2

Step 1 – Setup developer environment

Create a developer environment for Sitecore Commerce to run the engine from Visual Studio, can be either VS 2017 or 2019. Follow this blog post for same Setup development environment for Sitecore Commerce 9.3 Engine

Step 2 – Install Visual Studio Extension for creating plugin

  1. Go to  solution root folder or SDK folder and run the Sitecore.Commerce.Plugin.vsix file. Close the Visual Studio solution if open.
  2. This should install extension on selected Visual Studio Version
create plugin1

Step 3 – Create a plugin

  1. Open your solution. Create a Feature solution folder, just to follow Helix best practice. Right click solution folder to create a new project
  2. Search Sitecore.Commerce.Plugin. Select project type and click next.
create plugin2
  1. Give the project name, location and select .Net Framework 4.7.1. Create a Project.
create plugin3
  1. Sample Folder and Files for Commands, Components, Controller etc shall be added.
create plugin4
  1. Update the Sitecore Commerce Core from 5.0.0 to 5.0.4
create plugin5
create plugin6

4. Build the project. There shouldn’t be any reason the build should fail.

Step 4 – Reference project and run engine

  1. Add Plugin project reference to your Commerce.Engine Project
  2. Run the Engine. You should be able to see the newly created plugin is now registered in Engine.

This should allow to start customizing commerce and truly use plug-gable and extendable feature of Sitecore Commerce.

create plugin9

We intentionally didn’t add any code to this plugin to keep this simple. In the next blog, we will cover the anatomy of the newly created plugin and show how to inject this plugin into Commerce Pipelines and execute some custom code.

Next understand the Elements of Sitecore Commerce Plugin project templates

Hope you enjoyed this post. Stay tuned.

Step-by-step – Setup development environment for Sitecore Commerce 9.3 Engine

On a XC installed instance you might want to customize the XC by adding your own Entities, Components, Entity Views etc. In this topic I will describe how to setup your development environment to add your custom plugin.

This topic assumes a Sitecore CMS and Commerce engine version 9.3 are running under IIS. I am using Visual Studio 2019.

Steps to setup-

Step 1- Extract Commerce Engine SDK

  1. Copy the downloaded SDK Sitecore.Commerce.Engine.SDK.5.0.76.zip on your development folder.
  2. If not available you may download Packages for On Premise WDP 2020.01-5.0.145
  3. Extract the commerce package and then extract Sitecore.Commerce.Engine.SDK.5.0.76.zip
Extracted files

Step 2 – Setup Visual Studio Solution

  1. Open the Solution, by default this is Customer.Sample.Solution.sln
  2. Ensure Package Source is configured for Commerce- https://sitecore.myget.org/F/sc-commerce-packages/api/v3/index.json
  3. Build the Solution. It should restore the package and build successfully.
  4. (optional)Rename the Solution name. In this case I have renamed to Retail.Commerce
  5. (Optional) Create a solution folder “Project” and move Sitecore.Commerce.Engine project
  6. (Optional) Rename “Sitecore.Commerce.Engine” project to “Retail.Commerce.Engine”. Re reference AdventureWorks, Habitat and BrainTree projects if required. Adjust/rename namespace in classes.
  7. (Optional) Create Foundation and Feature projects. Build the solution again.
CompileVS

Step 3 – Generate Development Certificate

Generate development certificate using script “New-DevelopmentCertificate”, so the localhost runs on SSL(https)

  1. Open powershell script and navigate to scripts folder.
  2. Execute New-DevelopmentCertificate script
  3. Change the Path($certificateOutputDirectory) if required. Certificate should be copied to \src\Project\Engine\code\wwwroot
generate_certificate
generate_certificate1

Step 4 – Update configuration

  1. Change environment in Engine project/wwwroot/config.json file to HabitatAuthoring
  2. Change “SitecoreIdentityServerUrl”: “https://storefront930.identityserver.local”,
  3. Add the site name in AllowedOrigins in config.json
  4. Open Global.json in  wwwroot/bootstrap folder in Engine project
  5. Update SQL Server, UserName and Password in EntityStoreSqlPolicy
  6. Check the database name
globalconfig1

7. Update Host to your site host name in SitecoreConnectionPolicy

globalconfig2

Note: You may copy the config.json and gloal.json file from Authoring Site hosted in IIS to your project, but to better understand the changes required I have noted the changes. 

Step 5 – Update allowed origins in Identity Site

  1. Open Sitecore.Commerce.IdentityServer.Host.xml file. Should be in /config/production/Sitecore.Commerce.IdentityServer.Host.xml
  2. Navigate to section <CommerceEngineConnectClient><AllowedCorsOrigins>
  3. Add https://localhost:5000 to the

Step 6 – Ready for running the Engine

  1. Set Engine as your Startup Project
  2. Change the debug profile to “Engine” instead of “IIS Express”
  3. In IIS stop Authoring site. i.e. for your default instance it might be CommerceAuthoring_sc930 site
  4. Run the Engine from Visual Studio. This will open the console.
  5. Once the plugins are instantiated, it should listen to 5000 port. At this point you have configured Engine to run/debug from Visual Studio. Any calls from the business tool should be received by engine and console should be able to show the request that’s been received.
RunVSComm1
RunVSComm3

And here we have business tool sending request to engine running on Visual Studio, see GetNavigationView() been called in console-

Bixfx
RunVSComm4

Sitecore Commerce – Product listing page error- The Layout for the requested document was not found

Each Storefront in Sitecore Commerce has its own Storefront settings and Catalog configuration. Whilst configuring multiple environment in a single Commerce instance you might come up with the layout not found error on the Product Listing or Details page.

StorefrontConfiguration

If you see the image above the path is directly been severed from Sitecore Content i.e. a direct navigation is used. To resolve this issue goto- /sitecore/Commerce/Commerce Control Panel/Storefront Settings/Storefronts/Storefront/Catalog Configuration

Uncheck Use Direct Navigation

StorefrontConfiguration_resolve

The product listing and details page should be shown.

StorefrontConfiguration_resolve)product

 

Step by Step – Create promotions in Sitecore Commerce 9.3

Who don’t like discounts. People eagerly wait for Black Friday or Christmas offers. During festive these are the discounts applied mostly without a promo codes. When its no festive period you may still find the discounts but those asks for promo codes i.e. coupons.

giphypromo

In this article I will walk through how to create and setup the promotions in Sitecore Commerce 9.3  by defining qualifications, benefits and coupons. How the discounts are automatically applied when Public Coupons are set and how to restrict an auto discounts by setting private coupons.

I assume you have installed Sitecore Experience and Commerce 9.3.

See these links more details on Creating and Setting Promotions step by step

Step 1- Promotion dashboard and Promotion Book

To be continued…

 

 

 

 

 

 

 

Sitecore Commerce – Promotion Dashboard and creating Promotion Book in Business Tool

1. Promotion dashboard

Promotion dashboard shows all Promotion Book where all the Promotions are kept. Dashboard allows to add new Promo book.

PromoDashboard

2. Creating a Promo Book

All promotions are organised in a promo book. The list of promotion books on the Promotion dashboard is shown in alphabetical order. Promotion dashboard has options to Add new promotion book. By default Habitat_PromotionBook is created in the Commerce is installed.

To add new promotion book click on Add icon. This should show the popup to add a new promo book.

PromoBookAdd

Promo book with same name cannot be added.

PromoBookAddError1

Promo book name should not exceed 50 characters.

PromoBookAddError2

 

Sitecore commerce – No catalog data available

Sitecore Storefront can have multiple catalogs, but only one catalog can be used to each Storefront.

At times whilst development you might have to switch between the Authoring site and Visual Studio Commerce Engine Solution for debugging. I have seen sometimes the Catalog for the Storefront is reset during the switch which results in error – No catalog data available.

This message is shown on the menu as seen in the screenshot-

ErrorNoCatalogDataAvailable

ErrorNoCatalogDataAvailable2

Solution-

Login to Sitecore Client and follow these steps-

  1. Navigate to following location in Content Editor-  /sitecore/content/Sitecore/Storefront/Home/CatalogsSelectCatalog
  2. If none of the Catalog is selected, please select the Catalog and Save. In this case Habitat_Master
  3. Should now display the menu as the Catalog details are now setupErrorNoCatalogDataAvailable1

You also might need to consider checking Catalog Configuration here – /sitecore/content/Sitecore/Storefront/Settings/Commerce/Catalog Configuration

Setup the Catalog and Start Navigation Category

CatalogConfiguration

 

Hope this helps.

 

 

Sitecore Commerce environments- configure and access environment policy

Environments in Sitecore XC are used to control the configuration policies that defines behavior. Define a Commerce environment in the environment configuration JSON file. JSON file contains information specific to Commerce Engine policies that needs to be implemented for specific environment for example Habitat Authoring.

In this article will show how to configure the policy in a specific environment JSON file and access the policy that affects the behavior based on the settings.

First check the default environment. Open Sitecore.Commerce.Engine.Connect.config and see

<defaultEnvironment>HabitatAuthoring</defaultEnvironment>

In this case will add a setting to include Sitecore Clinet Url in enviornment-

Open Comerce Authoring – wwwroot\data\Environments folder

Since the default environment is HabitatAuthoring, you should update PlugIn.Habitat.CommerceAuthoring-1.0.0.json file-

{
"$type": "Sample.Commerce.Plugin.Management.Policies.SitecoreCmsServerPolicy, Sample.Commerce.Plugin.Management",
"ServerHostName": "https://mystorefront.local/"
},

Restart IIS. Hope you already know how to run the Commerce Ops script using postman.

Open Postman, run the GetToken and in SitecoreCommerce_DevOps

run Bootstrap Sitecore Commerce.

This should sync the environment related changes.

Assuming you have a plugin. Create a policy in  Sample.Commerce.Plugin.Management.Policies namespace with the class SitecoreCmsServerPolicy inherited from Policy as below-

using Sitecore.Commerce.Core;

namespace Sample.Commerce.Plugin.Management.Policies
{

public class SitecoreCmsServerPolicy: Policy
{
public string ServerHostName { get; set; }
}
}

You can use the environment configurations by getting the policy as folloes-

var cmsSitecoreServerPolicy = context.GetPolicy<SitecoreCmsServerPolicy>();

cmsSitecoreServerPolicy.ServerHostName;

You should now get the value “https://mystorefront.local/” when ServerHostName is accessed.

You may update these environment files- PlugIn.Habitat.CommerceShops-1.0.0.json for shops environment

Hope this helps.

 

Reference- Commerce Engine environments

 

 

 

 

 

 

Sitecore commerce (XC) 9.2 installation errors

Whilst installing XC 9.2 I faced following issues, these are basic issues but as a newbie was a good learning and a in depth understanding of the configurations and tasks required to get the commerce installed.

Configuration contains no tasks

This was the trickiest issue. XC9.2 required SIF 2.1.0, you might have installed this version but if you have multiple versions of SIF you might have to switch to SIF 2.1.0 whilst installing the XC9.2

Following is the coupe of lines, end of the scripts ends during installation-

VERBOSE: Registering Task extension ‘TestWebFeatureSSL’ => ‘Test-WebFeatureSSL’
VERBOSE: Registering task parameter map
VERBOSE: WarningAction => Continue
VERBOSE: Verbose => Continue
VERBOSE: InformationAction => Continue
VERBOSE: WhatIf => False
VERBOSE: Debug => SilentlyContinue
VERBOSE: ErrorAction => Stop
WARNING: Configuration contains no tasks
[TIME] 00:00:00

Solution to issue-

Check the version of SIF active in the powershell or currently used with following command-

Get-Command -Module SitecoreInstallFramework | Select-Object -Property name, version

XC1

Resolution-

If it shows V1.2.1 switch to version 2.1.0 but ensure the this version is installed. To switch to the new version-

Remove-Module -Name SitecoreInstallFramework
Import-Module -Name SitecoreInstallFramework -RequiredVersion 2.1.0

This should allow you to proceed with the instllation.

How I found this might be the issue-

Firstly its a pre-requisite to XC9.2, SIF 2.1. is required.

When I ran the installation script it showed this screen. It shows SIF version as 1.2.1, this were I guessed version might be wrong.

Logs didn’t mention the same.

ConfigurationTask

https://sitecore.stackexchange.com/questions/20791/xc-9-2-installation-error-configuration-contains-no-tasks

.Net SqlClient Data Provider: Invalid object name ‘Blobs’

This happens to be another silly mistake I made in the script file where I mentioned wrong site name prefix.

Found that it tries to update the Blobs and other tables in XP instance i.e. YourSitecoreXP_Master DB

So if the Sitecore prefix in the deploy script is wrong it tries to create a new database and update the Blobs table which is not available and hence fails.

 

XC2

Resolution-

So please check $SiteNamePrefix in deploy script, should match to the XP prefix. e.g.- if your Sitecore XP site name is storefront920.local so the database will be created as storefront920_Master. So in this case $SiteNamePrefix will have to be storefront920

Invoke-RestMethod : The remote server returned an error: (500) Internal Server Error

If you see this error-

VERBOSE: Result: https://commerceshops.sc920.local/commerceops/Bootstrap()
BootStrapping Commerce Services: https://commerceshops.sc920.local/commerceops/Bootstrap()
VERBOSE: PUT https://commerceshops.sc920.local/commerceops/Bootstrap() with 0-byte payload
Install-SitecoreConfiguration : The remote server returned an error: (500) Internal Server Error.
At E:\sc_com_install\SIF\sc_com_install.ps1:100 char:1
+ Install-SitecoreConfiguration @params -Verbose *>&1 | Tee-Object “$PS …
+ ~~~~~~~~~~~~~~~~~
+ CategoryInfo : NotSpecified: (:) [Write-Error], WriteErrorException
+ FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Install-SitecoreConfiguration

Resolution-

Managed to resolve this issue by updating the Sql database name to have double slash “\\” between the machine name and sql instance.

This is applies to following paramsters in script-

CommerceServicesDbServer and SitecoreDbServer

e.g.:- machinename\\sql-instance

Could not load file or assembly (Microsoft.Web.XmlTransform.dll)

If you see below error even if the file is present in the desired location, Unblock the file to continue the installation.

XCERROR

Go to directory having files Microsoft.Web.XmlTransform.dll. Right click the dll and Unblock the dll

scerror2

If you still see this issue, provide the relative path to the dll in script file for parameter – MergeToolFullPath

© 2021 Sandeep Pote

Theme by Anders NorénUp ↑