Sitecore Commerce 10- Setup Development Environment for Business Tools

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
  • 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

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

  • 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

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

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&#8221;,
  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

Resharper – My most used shortcuts

Ctrl + T – Find anything in Visual Studio Solution

Fastest way to find files in your visual studio solution. Press this shortcut and start typing the keyword to navigate to your desired file.

Ctrl E + C – Code Cleanup

Re-sharper allows to clean code based on the defined tasks. Configure the tasks for C#, Html , CSS, Javascript etc. and follow the action after pressing this shortcut.

Ctrl R + R – Rename

The Rename refactoring allows you to rename any symbol, including: namespaces, types, methods, parameters, local variables, properties, fields, and events. It automatically finds and corrects all references to the symbol. The Rename refactoring can be invoked directly from the editor and sometimes from other views (Class View, Object Browser).

Ctrl + Alt + D – Todo explorer

Although nobody likes tech debt but there are instances when on an agile projects few tasks are to be pushed back to the future sprint. In such cases a TODO comments are applied. Re-sharper gives a feature to view such TODO items and a best practice its good to fix the TODO items before a production code is ready. Please this shortcut to view all the TODO items in your solution/project

Alt + Enter + Enter

Shortcut helps to rename the file same as the class name. These instances might come after the file (e.g.: .cs) is created and you decide to change the

 

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.