Walkthrough: Getting started with Business Tools customization

Abstract

How to set up a XC Business Tools development environment and compile the application using the Sitecore BizFX SDK.

The Sitecore Experience Commerce release package (for on-premise solutions) includes the Sitecore.BizFX.SDK, a software development kit (SDK) that contains Angular framework components that help you get started with your XC Business Tools customization projects.

This walkthrough describes the basic steps to set up the Sitecore BizFX SDK to get started with your XC Business Tools customization project.

Prerequisites

Before you perform the procedures in this walkthrough:

You must have a working instance of the Commerce Engine deployed in your development environment.
Ensure that you have the following environment and tool installed on your workstation
- the Node.js® JavaScript runtime environment
  Note
  You must use Node.js release 14.*
- the Angular CLI tool

Set up the Sitecore.BizFX.SDK development solution

To set up the Sitecore.BizFX.SDK for development:

Open the folder containing the Sitecore XC release package, and extract the content of Sitecore.BizFX.SDK.*.*.*.zip file into the location of your choice, for example, C:\projects\.

Add the Sitecore public feed for NPM packages in your npm configuration

The Sitecore.BizFX.SDK relies on NPM packages that are available on the Sitecore official public feed for NPM packages. You must ensure that your machine can connect to the feed to access the NPM resources.

To add the NPM packages feed to the config file:

Open the file: C:\Users\[your user]\.npmrc, and add the following files:

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

Note

If the .npmrc file does not exist on your machine, run the the following commands to create it, with the required feed URLs:

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/

Update the Business Tools config.json file with your deployment configuration

In the Sitecore.BizFX.SDK folder, a config.json file contains configuration parameters that you must update with the values specific to your deployment.

To update the configuration parameters:

In the folder where you extracted the Sitecore.BizFX.SDK.*.*.*.ZIP, open the src\assets\config.json file.
If your deployment does not use the default Habitat Authoring environment ("EnvironmentName": "HabitatAuthoring"), update the "EnvironmentName" parameter value to match the name of the authoring environment of your deployment.

Replace all values prefixed with "PlaceholderFor<context>" with the actual values of your deployment (the default location is inetpub\wwwroot\SitecoreBizFxSite\assets\config.json). The following shows an example of the values prefixed with "PlaceholderFor..." that you must replace.

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

Note

In a basic development scenario, we recommend that you use the default values of the LanguageCookieName and EnvironmentCookieName properties.

Update the Commerce Engine Authoring service configuration

You must update the configuration of the Authoring service on the Commerce Engine to accept requests from the Business Tools application.

To update the Authoring service configuration:

In your Commerce Engine development environment, open the Authoring service config.json file, for example \inetpub\wwwroot\CommerceAuthoring_Sc\wwwroot\config.json.
In the "AppSettings" section, update the value of the "AllowedOrigins" to specify "http://localhost:4200". For example:
```
"AllowedOrigins": "<your deployment values>|http://localhost:4200",
```
Bootstrap the Commerce Engine to load the configuration into the Global database.

Update the Sitecore Identity service configuration

You must update the Sitecore Identity Service configuration to accept the localhost port 4200 as a client.

To update the Sitecore Identity service configuration:

In your Commerce Engine development environment, in the Sitecore IdentityServer service folder, open the Sitecore.Commerce.Identity ServiceHost.xml file. For example, open \inetpub\wwwroot\<yourDeployment>-IdentityServer\wwwroot\Config\production\Sitecore.Commerce.IdentityServer.Host.xml.

In the <Clients> section, change the value of the <AllowedCorsOriginsGroup1> to <your_deployment_values>|http://localhost:4200.

For example:

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

</AllowedCorsOrigins>

Save your changes

Install SPEAK and BixFX packages

In order to build the Business Tools (BizFX) solution, you must first install the required SPEAK and BizFX packages.

Note

You must make sure to install the version of the Sitecore Business Tools that is included with the version of Sitecore Experience Commerce that you are using.

Open your preferred CLI tool, and, from the folder where you previously extracted the Sitecore.BizFX.SDK, run the following commands:

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

Build and deploy the BizFx sample solution project

To build and deploy the sample BizFx application:

To build the solution, in a CLI window, run the command ng build .
Note
To obtain a solution optimized for production, execute the ng build --configuration production command.
The Angular application build process compiles the solution into an output folder named dist located in the workspace folder. Within the dist folder, the sdk solution is the equivalent of the <BizFx> website folder in the web root.
To deploy the BizFx solution, copy the content of the dist/sdk folder into the <web root>\<BizFx> folder.