2 min read

How to configure and run BFC API locally

In this section we will explain how to configure BFC API to run locally. Please note that as long as we are using an API that is communicating with Salesforce Commerce Cloud via Open Commerce API it will require a corresponding set of configuration parameters.

Prerequisites

Sfcc powered BFC API generated from the template
Poq Application Identifier (for this section it can be any GUID)
Poq App Id (for this section it can be any integer value)
OCAPI ClientId with all required permissions set
OCAPI base Url
Website checkout url

Steps

Check out the newly generated appsettings.Development.json file. It will look something like this, with all the required keys empty or replaced with wildcards.

{
 "Logging": {
   "Console": {
     "IncludeScopes": true
   }
 },
 "PoqPlatform": {
   "Url": "https://dev.poq.io"
 },
 "Http": {
   "TimeoutInMilliseconds": 10000
 },
 "Apps": {
   "#{clientAppIdentifier}#": {
     "AppId": "#{clientAppId}#",
     "Sfcc": {
       "ClientId": "#{ocapiClientId}#",
       "BaseUrl": "#{ocapiBaseUrl}#",
       "Version": "v21_6",
       "Currency": "USD"
     },
     "CheckoutUrl": "",
     "DefaultCookieDomain": "",
     "PdpImagesViewType" : "large",
     "PlpImagesViewType" : "medium",
     "SwatchImagesViewType": "swatch",
     "LowOnStockThreshold": 10,
     "StoreFinderCountryCode": "US",
     "StoreFinderSearchRadius": 1000,
     "StoreFinderDistanceUnit": "mi"
   }
 },
 "Redis": {
   "ConnectionString": "#{redisConnectionString}#"
 }
}

In general BFC API can serve more than one app for the same client. Therefore every app specific configuration is grouped by clientAppIdentifier. Usually app specific configuration is based on the region of the app. In order to configure API to run locally you will need to specify following settings in appsettings.Development.json file:
1. Apps.ClientAppIdentifier [required] - poq app client identifier
2. Apps.[clientAppIdentifier].AppId [required] - legacy poq app client identifier (is going to be retired soon, still specified as required by old CMS)
3. Apps.[clientAppIdentifier].[Sfcc].ClientId [required] - OCAPI client id
4. Apps.[clientAppIdentifier].[Sfcc].BaseUrl [required] - OCAPI base url
5. Apps.[clientAppIdentifier].[Sfcc].Version [required] - OCAPI version
6. Apps.[clientAppIdentifier].[Sfcc].Currency [required] - Currency Code
7. Apps.[clientAppIdentifier].CheckoutUrl [required] - web checkout url
8. Apps.[clientAppIdentifier].DefaultCookieDomain [optional] - if OCAPI does not set required cookie domain it can be specified via this setting, if set will be setting specified values for all the cookies
9. Apps.[clientAppIdentifier].PdpImagesViewType [optional] - you can customize the view type to use for PDP images
10. Apps.[clientAppIdentifier].PlpImagesViewType [optional] - you can customize the view type to use for PLP images
11. Apps.[clientAppIdentifier].SwatchImagesViewType [optional] - you can customize the view type to use for Swatch images on PDP
12. Redis.ConnectionString [optional] - Redis connection string, optional for Debug runs, required for the Release runs, is placed in corresponding configs during release phase
13. Apps.[clientAppIdentifier].LowOnStockThreshold [optional] - low stock threshold indicator
14. Apps.[clientAppIdentifier].StoreFinderCountryCode [optional] - store finder country code
15. Apps.[clientAppIdentifier].StoreFinderSearchRadius [optional] – store finder search radius
16. Apps.[clientAppIdentifier].StoreFinderDistanceUnit [optional] – store finder distance unit

Final config example:

{
 "Logging": {
   "Console": {
     "IncludeScopes": true
   }
 },
 "PoqPlatform": {
   "Url": "https://dev.poq.io"
 },
 "Http": {
   "TimeoutInMilliseconds": 10000
 },
 "Apps": {
   "e72931aa-6ddd-4952-9c7b-d31ae5488845": {
     "AppId": "10",
     "Sfcc": {
       "ClientId": "3dea4d1b-f703-42f2-93d2-0ce34d2f3371",
       "BaseUrl": "https://zzyd-001.sandbox.us01.dx.commercecloud.salesforce.com/s/RefArch",
       "Version": "v21_6",
       "Currency": "USD"
     },
     "CheckoutUrl": "https://zzyd-001.sandbox.us01.dx.commercecloud.salesforce.com/s/RefArch/cart?lang=en_US",
     "DefaultCookieDomain": ".salesforce.com",
     "PdpImagesViewType" : "large",
     "PlpImagesViewType" : "medium",
     "SwatchImagesViewType": "swatch",
     "LowOnStockThreshold": 10,
     "StoreFinderCountryCode": "US",
     "StoreFinderSearchRadius": 1000,
     "StoreFinderDistanceUnit": "mi"
   }
 },
 "Redis": {
   "ConnectionString": "#{redisConnectionString}#"
 }
}

Now you can configure integration unit tests. Go to Poq.Api.YourBrand.Integration.Tests.IntegrationTestsBase and set AppIdentifier and AppId to corresponding values from the config

protected string AppIdentifier = "e72931aa-6ddd-4952-9c7b-d31ae5488845";
protected string AppId = "10";

Run Integration.Tests. They should all pass now.

One integration test can be failing at this point GetContentAsyncShould.ReturnAccountContentResponse() if CMS was not set up yet. If it is failing at this point just comment it out and put it back in once CMS has been configured.

Run Api locally.

Check Swagger documentation page via adding /docs to your url.

Invoke test request against the Api using Swagger. Let us invoke /shop endpoint. To do that we only need to fill AppIdentifier parameter.

Technically speaking we already invoked our API by means of Integration Unit Tests, you can find more info about integration tests in corresponding HowTos section.

Congratulations! You have successfully configured and run BFC API locally.

Make sure to remove all sensitive data from Dev config before committing it. Make sure to replace all the sensitive values that are required for the integration tests to run with wildcards, for example "ClientId": "3dea4d1b-f703-42f2-93d2-0ce34d2f3371" -> "ClientId": "#{ocapiClientId}#". These wildcards will be replaced during the CI/CD Build step to allow tests to pass. Please see the corresponding HowTo section below.

How to configure and run BFC API locally

Prerequisites

Steps

See Next