Working with the BizFx SDK: Preparing the Base Solution for Customisation

In this article, we will look at preparing the BizFx project for customisation, by first aligning the default configuration of the SDK with the configuration that was deployed with the Sitecore Commerce installation, and then reviewing how to build and deploy solution.

Fair warning: I am not an expert in Angular, however the information provided is enough for getting started and performing the bare minimum to align the BizFx SDK for custom solutions.

Creating the BizFx Development Solution

The Sitecore Commerce On Premise package contains the BizFx SDK and the speak files that will be required for the new project.

Extract the contents of the Sitecore.BizFX.SDK.*.*.*.zip into your desired folder location, e.g. C:\projects\, and copy the speak-ng-bcl-*.*.*.tgz and speak-styling-*.*.*-r*****.tgz files into the same folder as the SDK.

The BizFx SDK does come with a README.md file containing some general instructions on preparing the solution for building, however we will highlight the main aspects of these instructions and cover some addition steps for local and production deployments.

In src\assets\config.json we need to copy the values from our local BizFx installation, located by default at <web root>\<BizFx>\assets\config.json, so that when we deploy our new version the configuration isn't corrupted. You'll notice the values that need to be updated are named 'PlaceholderFor<context>'.

{
  "EnvironmentName": "HabitatAuthoring",
  "EngineUri": "PlaceholderForAuthoringUrl",
  "IdentityServerUri": "PlaceholderForIdentityServerUrl",
  "BizFxUri": "PlaceholderForBizFxUrl",
  "Language": "PlaceholderForDefaultLanguage",
  "Currency": "PlaceholderForDefaultCurrency",
  "ShopName": "PlaceholderForDefaultShopName",
  "LanguageCookieName": "selectedLanguage",
  "EnvironmentCookieName": "selectedEnvironment",
  "AutoCompleteTimeout_ms": 300
}

The other value that will need to be updated for projects will be the EnvironmentName, which is used to select the default environment in BizFx.

It is recommended that the LanguageCookieName and EnvironmentCookieName properties remain as their default value as they may only need to be changed for advanced customisations. We will not cover modifying these properties in this article.

Prerequisites for Building

Assuming node installed already, from the BizFx solution folder, open your preferred CLI tool and run the following commands:-

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/
​​​​​​​npm install speak-ng-bcl-0.8.0.tgz
npm install speak-styling-0.9.0-r00078.tgz
npm install @sitecore/bizfx
npm install

Building and Deploying the BizFx Solution

For building the BizFx Angular application, the ng build command will compile into an output folder named dist, defaulting to the workspace folder. Within the dist folder, the sdk will be the equivalent of the <BizFx> website folder in the web root.

For production builds execute the ng build -prod command, which optimises the compiled solution for production deployments.

For more information about the Angular commands see https://angular.io/cli.

To deploy the BizFx solution, copy the contents of the dist/sdk into the <web root>\<BizFx> folder.

Building and Deploying via Gulp

For building and deploying the BizFx solution, I use a gulp script to wrap the angular commands. See the Source Code link at the end of the article to download the script.

If you haven't installed gulp, run the following command:-

​​​​​​​npm install gulp

Running the default gulp command will build the solution, clean out the BizFx folder in the web root and the deploy the solution to the BizFx folder.

As the gulp tasks will be performing operations on system restricted folders, make sure you run the gulp command under Administrator privileges.

Source Code: Ajsuth.BizFx.DeploymentScripts

Decoupling the Sample Plugins from the Sitecore Commerce 9 SDK

The Sitecore Commerce SDK comes with a number of sample plugins which serve varying purposes, including upgrading/migrating data from Sitecore Commerce 8.2.1, providing Habitat and AdventureWorks sample data for testing and getting familiar with the Commerce Engine's services, and a working Braintree payment integration.

Customer.Sample.Solution

In this article, we will look at the steps required to decouple the sample projects from the solution and resolve the dependencies that the Commerce Engine project has on them, to provide a clean starting point for customising and extending your project's instance of the Commerce Engine.

Note: We will leave the Braintree plugin in the solution so we can still checkout in the storefront. We will also leave the habitat environment configuration files, which can be updated to the custom environment names for your solution.

We will go into detail below, but let's take a quick look at what's required at a high level:-

  1. Add dependency references to the Commerce Engine
  2. Add necessary pipeline configurations to the Commerce Engine
  3. Remove policies for sample projects from the environment configuration files and policy sets
  4. Remove sample environment configurations and policies from the Commerce Engine
  5. Remove sample projects from the solution
  6. Test the Commerce Engine

Add Dependency References to the Commerce Engine

The following dependencies will need to be added to the Commerce Engine for the project to build once the sample projects have been removed:-

  • Sitecore.Commerce.Plugin.Coupons
  • Sitecore.Commerce.Plugin.Journaling
  • Sitecore.Commerce.Plugin.SQL
  • Sitecore.Commerce.Plugin.Tax

Note: For versioning, confirm with the other plugin references.

Add Necessary Pipeline Configurations to the Commerce Engine

The Commerce Engine is missing a few pipeline configurations that hook up some of the cart functionality. To resolve this, perform the following steps:

  1. Copy the ServiceCollectionExtensions class from the Plugin.Sample.AdventureWorks project into the Commerce Engine project at Pipelines > Blocks.
  2. Rename the namespace to Sitecore.Commerce.Engine.
  3. Copy the ConfigureSitecore class from the Plugin.Sample.AdventureWorks project into the Commerce Engine project.
  4. Rename the namespace to Sitecore.Commerce.Engine.
  5. Replace the ConfigureServices method with the following:
    public void ConfigureServices(IServiceCollection services)
    {
        var assembly = Assembly.GetExecutingAssembly();
        services.RegisterAllPipelineBlocks(assembly);
        services.ConfigureCartPipelines();
    }
  6. Resolve ConfigureCartPipelines by adding in the following to the class:
    using Sitecore.Commerce.Engine.Pipelines.Blocks;

Remove Sample Environment Configurations and Policies from the Commerce Engine

Highlighted in red are the properties, policies, and environment configuration files to be removed from the solution.

  • Global.json
    • EnvironmentList
      • "AdventureWorksShops"
      • "AdventureWorksAuthoring"
    • Plugin.Sample.Upgrade.MigrationPolicy
    • Plugin.Sample.Upgrade.MigrationSqlPolicy
  • PlugIn.AdventureWorks.CommerceAuthoring-1.0.0.json
  • PlugIn.AdventureWorks.CommerceMinions-1.0.0.json
  • PlugIn.AdventureWorks.CommerceShops-1.0.0.json
  • PlugIn.Habitat.CommerceAuthoring-1.0.0.json
    • Sitecore.Commerce.Core.EnvironmentInitializationPolicy
      • "Environment.Habitat.DefaultRelationships-1.0"
      • "Environment.Habitat.SellableItems-1.0"
      • "Environment.Habitat.Pricing-1.0"
      • "Environment.Habitat.Promotions-1.0"
      • "Environment.Habitat.Catalog-1.0"
    • Plugin.Sample.Customers.CsMigration.ProfilesSqlPolicy
    • Plugin.Sample.Customers.CsMigration.ProfilePropertiesMappingPolicy

Remove Sample Projects from the Solution

We can now remove the following projects from the solution:-

  • Plugin.Sample.AdventureWorks
  • Plugin.Sample.Customers.CsMigration
  • Plugin.Sample.Habitat
  • Plugin.Sample.Upgrade

The solution should now resemble the image below.

Test the Commerce Engine

To verify the solution:-

  1. Run the Commerce Engine project locally.
  2. Run the Bootstrap request, either via postman or browser.
  3. Run the CleanEnvironment request.
  4. Run the InitializeEnvironment request.