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 SPEAK 3 user interface elements and 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.

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

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

  1. 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\.

  2. In the Sitecore XC release package folder, copy the following files to the (unzipped) Sitecore.BizFX.SDK folder:

    • speak-ng-bcl-*.*.*.tgz

    • speak-styling-*.*.*-r*****.tgz

    • speak-icon-fonts-*.*.*.tgz

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/

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:

  1. In the folder where you extracted the Sitecore.BizFX.SDK.*.*.*.ZIP, open the src\assets\config.json file.

  2. If your deployment does not use the default HabitatAuthoring environment ("EnvironmentName": "HabitatAuthoring"), update the "EnvironmentName" parameter value to match the name of the authoring environment of your deployment.

  3. 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.

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:

  1. In your Commerce Engine development environment, open the Authoring service config.json file, for example \inetpub\wwwroot\CommerceAuthoring_Sc\wwwroot\config.json.

  2. In the "AppSettings" section, update the value of the "AllowedOrigins" to specify "http://localhost:4200". For example:

    "AllowedOrigins": "<your deployment values>|http://localhost:4200",
  3. Bootstrap the Commerce Engine to load the configuration into the Global database.

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

To update the Sitecore Identity service configuration:

  1. 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.

  2. 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>
  3. Save your changes

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-*.*.*.tgz
    npm install speak-styling-*.*.*-r*****.tgz
    nmp install speak-icon-fonts-*.*.*.tgz
    npm install @sitecore/bizfx
    npm install

    Note

    Ensure to replace the wildcard characters to match the file names in your release package.

To build and deploy the sample BizFx application:

  1. 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 -prod 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.

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