Category: Commerce

Install Sitecore Commerce 10.3 using SIF

Follow these steps to install Sitecore Commerce 10.3 On Premise. To successfully install refer to Installation Guide provided by Sitecore.

Before installing Sitecore Commerce install Sitecore XP 10.3. See this blog to install Sitecore XP 10.3 using SIF. Say the XP site name is- xp103.sc

Download Installation Guide

Hosting Environment Requirements/ Download and Install following software-

  1. OS – Windows Server 2019/2016 or Windows 10 Pro(64-bit) or Windows 11 Pro(64-bit)
  2. Redis (Windows): 3.0.504 (or later)
  3. Database – Microsoft SQL Server 2017 Express Edition (This should be already installed as a part of XP 10)
  4. Install Microsoft Web Deploy 3.6 if not already installed
  5. Install URL Rewrite using Web Platform Installer
  6. SOLR 8.11.2 (This should have already installed as a part of XP 10.3 install)
  7. Install PowerShell 5.1 or later is not already installed
  8. Web Platform Transformer (Download nuget package)
  9. (Important) Install Web hosting- here

IMPORTANT β€“ As per the release notes β€“

The deployment of SXA has been removed from the Commerce installation, and instead installed as a Platform pre-requisite before installing Commerce packages.

Sitecore PowerShell Extension for Sitecore on your local Sitecore instance if not already

Sitecore Experience Accelerator on your local Sitecore instance if not already

Also Commerce Ops service is removed from deployment configuration this will reduce deployment time and hosting cost.

Before starting the installation ensure XP 10.2 instance is working and indexed. If not indexed rebuild all search indexes-

Download Sitecore Experience Commerce 10.3

Step-by-step installation process-

1. Create a installation folder for XC – xcinstall for e.g.- C:\SCInstallation\103\xc103

2. Copy and extract Sitecore.Commerce.WDP.2022.12-9.0.82.zip file to C:\SCInstallation\103\xc103

3. Extract Web Platform Transfomer nuget package and copy Microsoft.Web.XmlTransform.dll to C:\SCInstallation\103\xc103

4. Extract SIF.Sitecore.Commerce.8.0.14.zip to C:\SCInstallation\103\xc103 folder. Rename this to SIF

Installation folder structure should look like this-

 Open Deploy-Sitecore-Commerce.ps1 file in SIF folder to update the following-

  • $XCInstallRoot
  • $XCSIFInstallRoot = β€œ$XCInstallRoot\SIF” or $PWD is fine – it is Present Working Directory,
  • $SiteNamePrefix
  • $SiteName
  • $SiteHostHeaderName [optional]
  • $MergeToolFullPath= β€œ$XCInstallRoot\Microsoft.Web.XmlTransform.dll”
  • $CommerceServicesDbServer = β€œβ€

12. Create Commerce Engine Connect Client Secret for the Sitecore Identity Server

  • Copy below script to file to scinstall/SIF folder example XC103SecretClientCertificate.ps1
  • Execute the script and copy secret key to $CommerceEngineConnectClientSecret
$bytes = New-Object Byte[] 32
$rand = [System.Security.Cryptography.RandomNumberGenerator]::Create()
$rand.GetBytes($bytes)
$rand.Dispose()
$newClientSecret = [System.Convert]::ToBase64String($bytes)
echo $newClientSecret

13. [Optional] Update Sitecore domain or keep it default

  • $SitecoreDomain
  • $SitecoreUsername
  • $SitecoreUserPassword
  • $UserName
  • $UserPassword

14. Update other DB related settings

  • $SqlUser
  • $SqlPass
  • $SitecoreDbServer
  • $CommerceServicesDbServer

15. Update SOLR details-

  • $SolrUrl
  • $SolrRoot
  • $SolrService

Execute .\Deploy-Sitecore-Commerce.ps1

 .\Deploy-Sitecore-Commerce.ps1

Storefront-

Business Tools-

Highly recommended to install commerce on fresh VM or machine that don’t have previously installed Sitecore Commerce to avoid any errors during isntallation. If not then below are few of the errors you might see during installation.

Errors-

00007 10:12:17 ERROR CtxMsg.Error.ContentPathAlreadyExists: Text=Content path ‘/sitecore/Commerce/Commerce Control Panel’ already exists.


00038 10:12:17 ERROR Management.block.getitembypath: Sitecore Item Service Get item failed, Item /sitecore/Commerce/Commerce Control Panel/Commerce Engine Settings/Commerce Terms/System Messages/ContentPathAlreadyExists not found.

Solution- see here – https://robearlam.com/blog/CtxMsg-Error-ContentPathAlreadyExists-error

Loading

Step by step install Sitecore XC 10.2 using SIF on Windows 11

Follow these steps to install Sitecore Commerce 10.2 On Premise. To successfully install refer to Installation Guide provided by Sitecore.

Before installing Sitecore Commerce install Sitecore XP 10.2. See this blog to install Sitecore XP 10.2 using SIF. Say the XP site name is- xp0.sc

Download Installation Guide

Hosting Environment Requirements/ Download and Install following software-

  1. OS – Windows Server 2019/2016 or Windows 10 Pro(64-bit) or Windows 11 Pro(64-bit)
  2. Redis (Windows): 3.0.504 (or later)
  3. Database – Microsoft SQL Server 2017 Express Edition (This should be already installed as a part of XP 10)
  4. Install Microsoft Web Deploy 3.6 if not already installed
  5. Install URL Rewrite using Web Platform Installer
  6. SOLR 8.2.0 (This should have already installed as a part of XP 10 install)
  7. Install PowerShell 5.1 or later is not already installed
  8. Web Platform Transformer (Download nuget package)
  9. (Important) Install Web hosting- here

IMPORTANT – As per the release notes

The deployment of SXA has been removed from the Commerce installation, and instead installed as a Platform pre-requisite before installing Commerce packages.

Install Powershell Extension for Sitecore – Download Sitecore PowerShell Extension for Sitecore

Install Sitecore Experiemce Accelerator 10.2.0 – Download Sitecore Experience Accelerator 10.2.0

Also Commerce Ops service is removed from deployment configuration this will reduce deployment time and hosting cost.

Before starting the installation ensure XP 10.2 instance is working and indexed. If not indexed rebuild all search indexes-

Download Sitecore Experience Commerce 10.2

Step-by-step installation process-

  1. Create a installation folder for XC – xcinstall for e.g.- c:\scinstallation\xc

2. Copy and extract Sitecore.Commerce.WDP.2021.11-8.0.218.zip file to c:\scinstallation\xc folder

3. Copy Sitecore Experience Accelerator 10.2.0 rev. 04247.zip file c:\scinstallation\xc folder

4. Copy Sitecore.PowerShell.Extensions-6.3 – IAR.zip file to c:\scinstallation\xc folder

5. Extract Web Platform Transfomer nuget package and copy Microsoft.Web.XmlTransform.dll to c:\scinstallation\xc folder

6. Extract SIF.Sitecore.Commerce.7.0.37 to c:\scinstallation\xc folder. Rename this to SIF

7. Folder structure should look like this-

8. Install Sitecore.PowerShell.Extensions-6.3 – IAR.zip package in your earlier installed Sitecore instance

9. Install Sitecore Experience Accelerator 10.2.0 rev. 04247.zip pakcagein your earlier installed Sitecore instance

11. Open Deploy-Sitecore-Commerce.ps1 file in SIF folder to update the following-

  • $XCInstallRoot
  • $XCSIFInstallRoot = “$XCInstallRoot\SIF” or $PWD is fine – it is Present Working Directory,
  • $SiteNamePrefix
  • $SiteName
  • $SiteHostHeaderName [optional]
  • $MergeToolFullPath= “$XCInstallRoot\Microsoft.Web.XmlTransform.dll”
  • $CommerceServicesDbServer = “sc102comm\MSSQL2017”

12. Create Commerce Engine Connect Client Secret for the Sitecore Identity Server

  • Copy below script to file to scinstall/SIF.Sitecore.Commerce.5.0.49 folder example XC10SecretClientCertificate.ps1
  • Execute the script and copy secret key to $CommerceEngineConnectClientSecret
$bytes = New-Object Byte[] 32
$rand = [System.Security.Cryptography.RandomNumberGenerator]::Create()
$rand.GetBytes($bytes)
$rand.Dispose()
$newClientSecret = [System.Convert]::ToBase64String($bytes)
echo $newClientSecret

13. [Optional] Update Sitecore domain or keep it default

  • $SitecoreDomain
  • $SitecoreUsername
  • $SitecoreUserPassword
  • $UserName
  • $UserPassword

14. Update other DB related settings

  • $SqlUser
  • $SqlPass
  • $SitecoreDbServer
  • $CommerceServicesDbServer

15. Update SOLR details-

  • $SolrUrl
  • $SolrRoot
  • $SolrService

Execute Deploy-Sitecore-Commerce.ps1 script to install commerce

IMPORTANT – After deployment is complete Disable TLS 1.3 over TCP for all the sites and all bindings

Errors-

Error -The remote server returned an error: (400) Bad Request. on GetIdServerToken

Resolution – Check your admin credentials if correctly configured in installation script.

Error – Commerce roles site not reachable

Resolution- Check if the SSL certificate for Comerce Engine is in Trusted Root Certification Authorities. If not copy the relevant certs to same.

Step by step guide to install Sitecore XP 10.2 using SIF on Windows 11

To install XP Single Developer(XP0) 10.2 on development machine, follow the steps in this blog post

Use the Sitecore Installation Guide for hardware, OS, database and other software requirements

Installation guide for XP Single (XP0) 

OS Requirements-

Windows 11 (64 bit)

Ensure IIS 10x installed

Ensure Powershell version 5.1 or later is installed. Check here the latest version

Install .Net Framework 4.8.0 – Download Developer Pack

Install .NET Core 3.1 Windows Hosting Bundle or later.

Install Microsoft Visual C++ 2015

Install Microsoft SQL Server 2017 Express Edition OR Install Microsoft SQL Server 2019 Express

You may also install the above prequisites using CLI. Goto section Install prerequisites before installing XP 10.2 after installing SQL Server and SIF

Install SQL Server Management Studio (SSMS)

This will ask you to restart your VM/Machine

  • Enable Contained Database Authentication

After installing SQL Server launch SQL Server Management Studio and run following-

EXEC sp_configure 'contained', 1;
 RECONFIGURE;

  • Install SIF Module
  1. Open PowerShell as an administrator.
  2. Set unrestricted execution to current user
Set-ExecutionPolicy -Scope CurrentUser Unrestricted

3. Register repository

Register-PSRepository -Name SitecoreGallery https://sitecore.myget.org/F/sc-powershell/api/v2

4. Install SIF

Install-Module SitecoreInstallFramework

5. After SIF installation check if the SIF 2.3.0 is installed

Get-Module SitecoreInstallFramework –ListAvailable 

To install specific version of SIF or run multiple version of SIF see this blog

Download XP Single Developer (XP0)

  • Prepare the installation folder

1. Extract downloaded XP Single Developer package to a folder e.g.:- C:\SCInstallation\XP102
2. Extract XP0 Configuration files 10.2.0 rev. 006766zip in same folder

  • Install prerequisites before installing XP 10.2

Switch to the installable e.g.:- C:\SCInstallation\XP102 folder and execute following script

Install-SitecoreConfiguration -Path .\Prerequisites.json
  • Install SOLR 8.4.0

1. Create a SOLR folder e.g.:- C:\SOLR and switch to e.g.- C:\SCInstallation\XP102  folder. Open Solr-SingleDeveloper.json file.

2. Change the Install Root for SOLR in Solr-SingleDeveloper.json – DefaultValue

 "SolrInstallRoot": {
            "Type": "String",
            "Description": "The file path to install Solr. This config will add the prefix and solr version e.g C:\Solr becomes C:\Solr\[SolrServicePrefix]Solr-8.4.0",
            "DefaultValue": "C:\\SOLR"
        },

3. Execute –

Install-SitecoreConfiguration -Path .\Solr-SingleDeveloper.json

Prepare and Execute script for installation

Open XP0-SingleDeveloper.ps1 file to update following-

  • $Prefix
  • $SitecoreAdminPassword
  • $SCInstallRoot – change path to the folder installers are available
  • $SolrUrl
  • $SolrRoot
  • $SolrService
  • $SqlServer
  • $SqlAdminUser
  • $SqlAdminPassword

Copy license to the e.g. – C:\SCInstallation\XP102  folder

Execute installation script – .\XP0-SingleDevelor.ps1

Error while installation

xconnect Marketing Automation fails to start-

Solution

Disable TLS 1.3 over TCP for xconnect. Rerun the installation script or disable this as soon as the xconnect bindings are setup by script during installation.

No registration for extension ‘AppPool’ of type ‘Task’

Solution

Check if the Asp.Net options in Windows features – Internet Information Services.

Sitecore Commerce Business Tools Compatibility Table

Sitecore Commerce installation package comes with Sitecore Business Tools SDK.

If you are planning to custommise Business Tools you might have to setup the development environment for Business Tools. You can find more information on how to setup the development environment here

For each version of Sitecore Commerce you need to install the specific version of Business Tools in you development environment.

See below the compatibility table for Business Tools with Sitecore commerce-

Package for the same can be found here

Sitecore Commerce (XC) VersionSitecore Business Tools VersionDownload Link
10.27.0.6https://sitecore.myget.org/feed/sc-npm-packages/package/npm/@sitecore/bizfx/7.0.6
10.16.0.6https://sitecore.myget.org/feed/sc-npm-packages/package/npm/@sitecore/bizfx/6.0.6
10.05.0.12https://sitecore.myget.org/feed/sc-npm-packages/package/npm/@sitecore/bizfx/5.0.12
9.34.0.8https://sitecore.myget.org/feed/sc-npm-packages/package/npm/@sitecore/bizfx/4.0.8
9.23.0.7https://sitecore.myget.org/feed/sc-npm-packages/package/npm/@sitecore/bizfx/3.0.7
9.12.0.3https://sitecore.myget.org/feed/sc-npm-packages/package/npm/@sitecore/bizfx/2.0.3
9.0.31.4.1https://sitecore.myget.org/feed/sc-npm-packages/package/npm/@sitecore/bizfx/1.4.1
9.0.21.2.19https://sitecore.myget.org/feed/sc-npm-packages/package/npm/@sitecore/bizfx/1.2.19
9.0.11.1.9https://sitecore.myget.org/feed/sc-npm-packages/package/npm/@sitecore/bizfx/1.1.9
9.0.01.0.572https://sitecore.myget.org/feed/sc-npm-packages/package/npm/@sitecore/bizfx/1.0.572

Sitecore XC 10 – code breaking changes

Sitecore Commerce 10

Sitecore Commerce supports integration to the third-part system and customization and extension to the OOTB entities. This can be achieved by custom plugins.

If you are migrating your code from XC 9.x version to XC 10 you will have to update the code to newest API’s provided with XC. Following is the list of breaking changes if migrating from older versions or good to know if you are starting with the new XC 10 solution.

Wrappers to PipelineBlock

Commerce Engine uses pipeline framework to support extensibility. Pipelines act as a containers for business logic. Commerce pipeline consists of a block which has a detailed business logic.

With Sitecore 10 PipelineBlock are now wrapped with AsyncPipeline and SyncPipeline. So if you have your code using PipelineBlock it should be using Run method to execute the block you may have injected to pipeline.

AsyncPipelineBlock

If block needs to be executed Asynchronously use AsyncPipelineBlock. Also the method name changes to RunAsync()

SyncPipelineBlock

If block needs to be executed Synchronously use SyncPipelineBlock. The method name used to execute block is Run()

ConfigureServiceApiBlock also now uses SyncPipelineBlock

2. IPipeline RunAsync() method

IPipeline interface method is changed from Run to RunAsync() which now makes sense as the method is asynchronous operation.

So where are the changes you might need to make, some of the pipelines that is used frequently and need change are listed below-

  1. IFindEntityPipeline
  2. IFindEntitiesInListPipeline
  3. IFindEntitiesPipeline
  4. IPersistEntityPipeline
  5. Any custom pipeline and list goes on…

Api Controller

Commerce api controller exposes the endpoint to communicate from FE or Commerce Connect to Commerce Engine. You can create custom endpoint and the api controller inherited from class CommerceController.

With XC 10.x the class file to inherit for same is CommerceODataController

See this link for more details – CommerceODataController

ODataActionParameters

ODataActionParameters should now be referenced from Microsoft.AspNet.OData namespace.

FileResultExecutorBase

FileResultExecutorBase should be referenced from Microsoft.AspNetCore.Mvc.Infrastructure

These are few of the breaking changes. There are more and I shall keep updating.

Sitecore Commerce 10 Business Tools- Part 2 – Create custom vertical view component

This is a Part-2 of customizing Sitecore Commerce Business Tools. To see how to setup the environment for customization before you could start creating a custom component see Part-1

Often you have seen entity details are shown in Flat view i.e. horizontally, fields and there values are displayed. If you have too many fields to display flat view doesn’t seem to be user friendly. In this case the best way to display such details will a vertical view.

This post assumes Instance of Commerce Engine deployed in development environment and a custom entity is created. This is just a example on how to extend Business Tools using Angular which shows the flexibility of Business Tools in terms of cusotmization.

I have a entity named Organization and captures details for same which has quite a few properties as seen in below screen-

There are around 10 fields in the details section of the entity. These fields are squeezed and also doesn’t look user friendly. This would go more ugly if there are more fields added in the entity.

Sitecore Entity View default UIHint is Flat where a single row is displayed in a form of table.

This would look better if it is displayed in Vertical View or Form View i.e. each field in a different row.

Lets see how this can be done using BizFx SDK and the development environment we have created in this post – <<ENTER SETUP DEV BUSINESS TOOL ENVIRONMENT LINK HERE>>

Sitecore business tools already have Flat and Table View. Flat been default. Lets create a new view called as Vertical View.

Open the folder where the SDK zip file was extracted and navigate to src/app/components/views folder

View folder should look like this-

Copy paste and rename following files-

  1. Copy and Rename sc-bizfx-flatview.component.css to sc-bizfx-verticalview.component.css
  2. Copy and Rename sc-bizfx-flatview.component.html to sc-bizfx-verticalview.component.html
  3. Copy and Rename sc-bizfx-flatview.component.ts to sc-bizfx-verticalview.component.ts

Open sc-bizfx-verticalview.component.html. Change the table to display the property name and value-

 <table scTable class="mb-0" *ngIf="view.Properties.length">
      <thead>
        <tr>
		<th>Property Name</th>
		<th>Property Value</th>
	</tr>
      </thead>
      <tbody>
		<tr *ngFor="let property of (view.Properties | isNotHidden)">
          <td>{{property.DisplayName}}</td>
		  <td>
            <div [ngSwitch]="property.OriginalType">
              <div id="property-{{view.Name}}-{{property.Name}}" *ngSwitchCase="'System.DateTimeOffset'" class="property">
                  <div *ngIf="property.UiType === 'FullDateTime'">
                      {{property.Value | date:'short':'':bizFxContext.language}}
                  </div>
                  <div *ngIf="property.UiType !== 'FullDateTime'">
                      {{property.Value | date:'shortDate':'':bizFxContext.language}}
                  </div>
              </div>

              <div id="property-{{view.Name}}-{{property.Name}}" *ngSwitchCase="'System.Decimal'" class="property">
                {{property.Value | number:'':bizFxContext.language}}
              </div>

              <div id="property-{{view.Name}}-{{property.Name}}" *ngSwitchCase="'Sitecore.Commerce.Core.Money'" class="property">
                {{property.Value | scCurrency:'code':'1.2-2':bizFxContext.language}}
              </div>

              <div id="property-{{view.Name}}-{{property.Name}}" *ngSwitchCase="'Html'" class="property">
                <div [innerHTML]="property.Value"></div>
              </div>

              <div id="property-{{view.Name}}-{{property.Name}}" *ngSwitchCase="'List'" class="property">
                <div *ngFor="let item of getList(property)">
                  {{item}}
                </div>
              </div>

              <div id="property-{{view.Name}}-{{property.Name}}" *ngSwitchDefault class="property">
                {{property.Value}}
              </div>
            </div>
          </td>
        </tr>
      </tbody>
    </table>

Add following to div having childViews loop to sc-bizfx-flatview.component.html-

<sc-bizfx-verticalview *ngIf="childView.UiHint === 'Vertical'" id="verticalView-{{childView.Name}}" [view]="childView"></sc-bizfx-verticalview>

Open sc-bizfx-verticalview.component.ts. Change the @Component and export Class name

@Component({
  selector: 'sc-bizfx-verticalview',
  templateUrl: './sc-bizfx-verticalview.component.html',
  styleUrls: ['./sc-bizfx-verticalview.component.css']
})
export class ScBizFxVerticalViewComponent {
  /**
    * Defines the view
    */
  @Input() view: ScBizFxView;

  /**
    * @ignore
    */
  constructor(
    public bizFxContext: ScBizFxContextService) {
  }

  /**
    * Helper method
    *
    * Parse the value of property with `UiType` of `List`.
    */
  getList(property: ScBizFxProperty) {
    return property.Value != null ? JSON.parse(property.Value) : [];
  }
}

Navigate to components folder. Open index.ts

Add- export * from ‘./views/sc-bizfx-verticalview.component’;

Navigate to app folder. Since a new class is registered this needs to be registered in app.module.ts file.

Open app.module.ts file. Add ScBizFxVerticalViewComponent to App Root import and to the @NgModule – declarations section-

import {
  ScBizFxActionComponent,
  ScBizFxActionBarComponent,
  ScBizFxFlatViewComponent,
  ScBizFxItemViewComponent,
  ScBizFxListPoliciesComponent,
  ScBizFxListViewComponent,
  ScBizFxSearchViewComponent,
  ScBizFxTableViewComponent,
  ScBizFxViewPropertyByTypeComponent,
  ScBizFxViewPropertyByUiComponent,
  ScBizFxViewPropertyTagsComponent,
  ScBizFxActionGridComponent,
  ScBizFxActionPropertyDateTimeComponent,
  ScBizFxActionPropertyTagsComponent,
  ScBizFxActionPropertyComponent,
  ScBizFxAutocompleteComponent,
  ScBizFxBraintreeComponent,
  ScBizFxMediaPickerComponent,
  ScBizFxViewComponent,
  ScBizFxVerticalViewComponent
} from './components';
declarations: [
    AppComponent,
    ScBizFxActionComponent,
    ScBizFxActionBarComponent,
    ScBizFxFlatViewComponent,
    ScBizFxItemViewComponent,
    ScBizFxListPoliciesComponent,
    ScBizFxListViewComponent,
    ScBizFxSearchViewComponent,
    ScBizFxTableViewComponent,
    ScBizFxViewPropertyByTypeComponent,
    ScBizFxViewPropertyByUiComponent,
    ScBizFxViewPropertyTagsComponent,

    ScBizFxActionGridComponent,
    ScBizFxActionPropertyDateTimeComponent,
    ScBizFxActionPropertyTagsComponent,
    ScBizFxActionPropertyComponent,
    ScBizFxAutocompleteComponent,
    ScBizFxBraintreeComponent,
    ScBizFxMediaPickerComponent,
    ScBizFxViewComponent,
    ScBizFxVerticalViewComponent
  ],

That’s all changes required to have a custom component in Business Tools.

Next open PowerShell and build the changes made and run the Business Tools site

ng serve

The site should now listen to 4200 port.

Now lets create/update a entity view with a Vertical view UIHint. I already have entity with the Flat view. I will change the UIHint to “Vertical” to display the properties and there values vertically.

Build and deploy engine changes to Authoring site. (Not covered in this blog)

Using Flat view either squeezes the table or a horizontal scroll which is not user friendly. With the Verticalview Organization details are now shown vertical with the Property Names and Values in different rows.

This view is more readable for user specially with the long text in Address.

Easy to implement and test on development environment you can build more complex controls with the same approach

Next post will see how to deploy these changes to production.

Hope you liked this post.

Sitecore Commerce 10 Create a custom plugin project

If you want to get started and create a custom plugin for XC 9.3 here is the post for same First Steps | Sitecore Commerce Development | Create a Custom Plugin

There are few updates on how the plugins are created in XC 10.

Sitecore Commerce 10 SDK does not include Visual Studio Extension (VSIX) package for creating a plugin project.

Let’s get started and look into the steps to create a new plugin in Sitecore Commerce 10. 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 10 Engine

Step 2: Download Sitecore.Commerce.Plugin.Template from Nuget Feed

  • Navigate to Official Sitecore Commerce Nuget Feed
  • Search for Sitecore.Commerce.Plugin.Template
  • Download the package for Sitecore.Commerce.Plugin.Template 6.0.4. Copy to file Sitecore.Commerce.Plugin.Template.6.0.4.nupkg desired folder.

3. Install Sitecore Commerce Plugin Template Nuget Package

  • Open Powershell in admin mode and navigate to the folder nupkg file is copied and execute following command to install package
dotnet new -i .\Sitecore.Commerce.Plugin.Template.6.0.4.nupkg
  • Run the dotnet new command and should be able to see Sitecore Commerce Sample Plugin template

4. Create a new Sitecore Commerce Plugin Project

As we have a plugin project template we should be able create a new plugin project.

Execute following command in Powershell. Navigate to the solution src folder-

dotnet new pluginsample -o Sitecore.Commerce.Plugin.SampleTest

New plugin project is created with the project name specified in command.

Include the project in Customer.Sample.Solution and compile.

Notice even though the command has project name “Sitecore.Commerce.Plugin.SampleTest” the actual project is created as “Sitecore.Commerce.Plugin.Sample”. You will have to rename this unfortunately as per your requirement.

Sharding Custom Entity in Sitecore Commerce 10

Sharding is horizontal partitioning of data in database. It is the process of breaking up large tables into smaller chunks.

Storing rows of the same table in multiple database nodes

In this blog post will see how to split the Commerce Entities table having same structure but store custom entity data in a separate table that helps to split the load that a CommerceEntities table might take if the horizontal partition is not done.

Why partioning of tables is required?

Sitecore Commerce entity data are store in following tables-

  • CommerceEntities
  • CommerceEntity
  • CommerceLists

Any custom entity been created without sharding will store data by default in tables mentioned above.

What if that data increases, there might be a performance hit once the data start expanding over months and years.

Also it wont be good idea to put the multiple custom entity data into a single table. As this might give a performance hit whilst indexing table. So, if you know data might increase over the time it is better to have it saved in a separate table as it can be a boon to high-volume data.

Partitioning data using sharding policy

I assume you know how extend Sitecore Commerce entities. Consider we have a “Organization” entity. Business Tools helps in capturing details of Organization i.e. CRUD operations. When the entity is been saved it has to be saved in different table.

This driven by the sharding policies in Commerce.

Follow these steps to enable sharding of custom entity-

Sharding Policies

The Commerce Engine implements database sharding for Commerce entity and list tables, and provides 2 types of sharding policies. One is for the operation against Commerce entities i.e. EntityShardingPolicy, and other on the Commerce lists i.e. ListShardingPolicy.

Configuration for sharding policy is kept in PlugIn.SQL.Sharding.PolicySet-1.0.0.json file and can be found in data\Environments folder of the Authoring and Shops instance.

As per Sitecore documentation sharding policies has expressions and multiple expression values can be configured based on this the table of the entity is identified to read and perform write operations. This is a bit contrary statement as the table name defined in policies are passed to the stored procedure based on this the data in table is written and read.

Below sharding policy mentions 2 tables-

OrganizationsLists for managing and reading lists of Organizations

OrganizationsEntities for managing and reading Organization entities

{
"$type": "Sitecore.Commerce.Plugin.SQL.ListShardingPolicy, Sitecore.Commerce.Plugin.SQL",
"Expressions": {
"$type": "System.Collections.Generic.List1[[System.String, mscorlib]], mscorlib",
"$values":
[
"^List-Organization.*?$"
]
},
"TableName": "OrganizationsLists"
},
{ 
"$type": "Sitecore.Commerce.Plugin.SQL.EntityShardingPolicy, Sitecore.Commerce.Plugin.SQL",
"Expressions": {
"$type": "System.Collections.Generic.List1[[System.String, mscorlib]], mscorlib",
"$values":
[
"^Entity-Organization.?$",
"^Organization-.?$"
]
},
"TableName": "OrganizationsEntities"
}

Database

To save data in different tables create Entities, Entity and Lists table prefixed with entity name in SitecoreCommerce_SharedEnvironments database

  1. Right click CommerceEntities table select Script Table as option, Create to and then New Query Editor Window. Create script for CommerceEntities table will be generated.
  2. Change the name of table to e.g.:- OrganizationsEntities. Also change the table name to set Default value to EntityVersion and Published fields
  3. Pasrse and check if you are creating a table in correct Database
  4. Execute the script. New table will be created.

Follow same for CommerceEntity table to create OrganizationsEntity and CommerceLists to create OrganizationsLists

So there are 3 tables created so far-

  • OrganizationsEntities
  • OrganizationsEntity
  • OrganizationsLists

Once you have your plugin to perform CRUD operations on Organizations entity you should be able to see the data been inserted in OrganizationEntities, OrganizationLists and OrganizationsEntity table instead of CommerceEntities and there related tables.

Sitecore Commerce 10- Setup Development Environment for Business Tools – Part 1

Business Tools is extensible using pluggable framework and can extend a UI using Entity Views. Although Business Tools offers a rich set of controls you might want to create your own custom control for the best business experience.

For this you need to first setup the development environment for business tools. Once the environment is setup you should be ready to develop custom control/customize the business tools.

Prerequisites

  1. Instance of Commerce Engine deployed in development environment
  2. Install Node.js Javascript runtime
  3. Install Angular CLI tool – npm install -g @angular/cli

NPM configuration to have NPM Packages from Sitecore public feed

Sitecore BizFx SDK relies on NPM packages available on the Sitecore official public feed for NPM packages.

Open Poswershell as Administrator

Execute these 2 commands in powershell

npm config set @speak:registry=https://sitecore.myget.org/F/sc-npm-packages/npm/

npm config set @sitecore:registry=https://sitecore.myget.org/F/sc-npm-packages/npm/

This will add following line to–

C:\Users\[your user]\.npmrc

[Optional] – you may check if this lines are added

@speak:registry=https://sitecore.myget.org/F/sc-npm-packages/npm/
@sitecore:registry=https://sitecore.myget.org/F/sc-npm-packages/npm/

Setup and Install SPEAK and BizFx packages for development solution

Copy Sitecore.BizFX.SDK.4.0.8 folder to your development folder and extract the SDK zip file to folder e.g. c:\BizFXDevelopment\SitecoreBizFx

Copy below files to the folder SDK was extracted. You should find this files from the Sitecore XC release package.

  1. speak-icon-fonts-1.1.0.tgz
  2. speak-ng-bcl-2.0.0-r00116.tgz
  3. speak-styling-1.0.0-r00110.tgz

Execute the following commands where the above files were copied

​​​​​​​npm install speak-icon-fonts-1.1.0.tgz
​​​​​​​npm install speak-ng-bcl-2.0.0-r00116.tgz
npm install speak-styling-1.0.0-r00110.tgz
npm install @sitecore/bizfx

Run npm install. This should install required npm modules and add a folder node_modules

npm install

Setup the business tools config.json with your deployment configuration

Once the npm installed successfully open config.json file located in src\assets folder

Update the config to the same as the BizFx site instance except for BizFxUri. Note BizFxUri points to http in below config

{
  "EnvironmentName": "HabitatAuthoring",
  "EngineUri": "https://localhost:5000",
  "IdentityServerUri": "https://xp10.IdentityServer",
  "BizFxUri": "http://localhost:4200",
  "Language": "en",
  "ContentLanguage": "en",
  "Currency": "USD",
  "ShopName": "CommerceEngineDefaultStorefront",
  "LanguageCookieName": "selectedLanguage",
  "ContentLanguageCookieName": "selectedContentLanguage",
  "EnvironmentCookieName": "selectedEnvironment",
  "AutoCompleteTimeout_ms": 300,
  "AccessTokenUpdateInterval_ms": 300000
}

Run the development environment

Important!

Stop the SitecoreBizFx site as the site listens to 4200 port. Next step will help listen the site from the extracted SDK folder.

Execute following Powershell command –

ng server

Open browser on http://localhost:4200/ this should ask to enter the Sitecore client credentials, once provided it will throw an error

This site can’t provide a secure connection

The reason this error occurs the identity server is not configure to server BizFx site on http

Update the Sitecore Identity Server Configuration

Open the Sitecore.Commerce.Identity ServiceHost.xml from the installed Identity Server instance \wwwroot\Config\production

Add http://localhost:4200 to AllowedCorsOriginGroup1

<AllowedCorsOrigins>
<AllowedCorsOriginsGroup1>http://localhost:4200</AllowedCorsOriginsGroup1>
</AllowedCorsOrigins>

Update Commerce Engine configuration

  • Open config.json from wwwroot folder in CommerceAuthoring site
  • Update AllowedOrigins in AppSettings to have http://localhost:4200
  • Since the config is changed need to bootstrap so the changes are applied to authoring site
  • Restart IIS. Optionally you may just restart Commerce Authoring site

Run Business tool from development environment

Open browser on http://localhost:4200/

Business tools running on http and in developer mode.

References –

step-by-step instructions on how to setup and compile the Business Tools (BizFX) application using the ​Sitecore.BizFX.SDK

Stay tuned next blog will walk through on how to create a new custom control/component in Business Tools

This image has an empty alt attribute; its file name is image-43.png

Setup development environment for Sitecore Commerce Engine 10 and 10.2

Update: Below is applicable for Sitecore Commerce 10.2. Change the SDK version accordingly. Ignore the step mention for Content Hub

Sitecore Experience Commerce 10 has come up with great new features like Dynamic Bundles, Free gift with Purchase promotion and a sample Sitecore DAM to Commerce connector.

Before you start looking into this, it is important to setup the development environment to debug and test the changes you are making to engine.

Main changes I could see compared to previous versions are integration with Content Hub and Configuring the Commerce Engine using environment variables which not only helps for on-premise installation of Commerce Instance but also helps setup the Docker technology where XC solution is running in containers.

In this post I will walk you through on how to setup the development environment. This post assumes you have Sitecore Commerce Engine along with Visual Studio 2019 installed on developer workstation. If Commerce not installed no worries see this post on how to install Sitecore XC 10 step-by-step.

Step-by-step install Sitecore Commerce (XC) 10

For previous version of XC you may follow this blog post

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

Step 1- Extract Commerce Engine SDK

  • Copy the downloaded SDK Sitecore.Commerce.Engine.SDK.6.0.130.zip on your development folder. e.g: c:\development. Note– there is an update on 19th August where the external dependencies are removed. Download the package again if you have a version before this date.
  • If not available you may download Packages for On Premise WDP 2020.08-6.0.238. Login before you download the file.
  • Extract the commerce package and then extract Sitecore.Commerce.Engine.SDK.6.0.130.zip in your development folder

Step 2 – Setup Visual Studio Solution

  • Open the Solution, by default this is Customer.Sample.Solution.sln
  • Ensure Package Source is configured for Commerce- https://sitecore.myget.org/F/sc-commerce-packages/api/v3/index.json
  • Whilst opening solution login from slpartners.myget.org will be prompted
  • Create an account on https://slpartner.myget.org/ and login here. You may unload Plugin.Sample.ContentHub project if you dont want to integrate ContentHub and the login should not require. Also note myget account has a trial for 14 days.
  • Build the Solution. It should restore the package and build successfully.
  • (optional)Rename the Solution name. In this case I have renamed to Retail.Commerce
  • (Optional) Create Foundation and Feature projects. Build the solution again.

Step 3- Important – Commerce Engine configuration

Sitecore.Commerce.Engine project should have a config.json file in wwwroot folder. Open this file you will see the placeholders that needs to be filled in.

Instead updating config file, you should update the launchSettings.json and the placeholders in config.json will be updated on launch on commerce engine.

Similarly Global.json you can find this in wwwroot/bootstrap folder of your Sitecore.Commerce.Engine project. Again this file has the Placeholders that will be populated from launchSettings.json,

You need to update mainly following variables in launchSettings.json file for both config and global json. There are other variables apart from listed below, you may need to update those based on your site instance name etc.-

  1. COMMERCEENGINE_Caching__Redis__Options__Configuration
  2. COMMERCEENGINE_GlobalDatabaseServer
  3. COMMERCEENGINE_GlobalDatabaseUserName
  4. COMMERCEENGINE_GlobalDatabasePassword
  5. COMMERCEENGINE_SharedDatabaseServer
  6. COMMERCEENGINE_SharedDatabaseUserName
  7. COMMERCEENGINE_SharedDatabasePassword
  8. COMMERCEENGINE_AppSettings__SitecoreIdentityServerUrl
  9. COMMERCEENGINE_EngineAuthoringUrl
  10. COMMERCEENGINE_EngineShopsUrl
  11. COMMERCEENGINE_EngineMinionsUrl
  12. COMMERCEENGINE_EngineHealthCheckUrl
  13. COMMERCEENGINE_AppSettings__AllowedOrigins

Step 4 – Generate Development Certificate

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

  1. Create a folder named “dev” in the root directory of SDK
  2. Create a folder named “Sitecore.Commerce.Engine_Dev” under “dev” folder
  3. Create a folder named “wwwroot” under “Sitecore.Commerce.Engine_Dev” folder
  4. Open powershell script and navigate to scripts folder.
  5. Change the Path($certificateOutputDirectory) if required. Certificate should be copied to \src\Project\Engine\code\wwwroot
  6. Execute New-DevelopmentCertificate script. This script should be available in script folder in SDK folder.

Step 5 – Update EngineUri in BizFx Site

  • Open config.json file. Should be in assets folder of your BizFx instance
  • Change EngineUri to https://localhost:5000
  • Change BizFxUri to https://localhost:4200
  • Restart BizFx site

Step 6- Run the Commerce Engine from Visual Studio

  • Set the Sitecore.Commerce.Engine project as Startup Project
  • Change the emulator to Engine
  • Stop the CommerceAuthoring_SC site hosted in IIS
  • Run the solution

Hope there should be nothing that should block to run the Business Tools requesting a call to Engine running from Visual Studio

Note: some places you may have to restart IIS also clear the browser cache before you start checking Business Tools is highly recommended.

Hope this post helps you setting your XC 10 development environment.

ISSUES

Request origin https://bizfx.sc.com does not have permission to access the resource

Resolution- Follow Step 5