SFRA Installation Guide

Prerequisites

  • You must have a storefront with a base cartridge up and running.
  • You must know the code version of your cartridge (Business Manager Administration > Site Development > Code Deployment).
  • Reach out to your Customer Success Manager to obtain the cartridge files.
  • If you are migrating from a different cart platform, see the Re-platforming section.

Upload Cartridge to SFCC DigitalServer

1. Configure

  1. Download the cartridge files sent by your Customer Success Manager.
  2. Rename the .zip file to bolt-demandware.
  3. Unzip the bolt-demandware folder.
  4. Run the following:
    npm install json
    json -I -f package.json -e "this.paths.base='<PATH TO APP_STORE_FRONT_BASE>'"
    
  5. In the root directory, run the following:
    npm ci
    
  6. Navigate to the directory that contains all of your Bolt cartridges.
  7. Create a configuration called dw.json and apply the following settings:
    {
    "hostname": "<*.demandware.net (without https/http)>",
    "username": "<username>",
    "password": "<password>",
    "cartridge": ["cartridge A", "cartridge B"], //optional
    "code-version": "<code-version>"
    }
    

2. Validate Configuration Changes

  1. Place all Bolt cartridges in your storefront’s cartridge folder.
  2. Open your storefront’s package.json file and locate “sites”: { “cartridges”: […] }.
  3. Add the following list of cartridges:
     {
          "alias": "bm_bolt",
          "name": "bolt_bm"
        },
        {
          "alias": "int_bolt_sfra",
          "name": "int_bolt_sfra"
        },
        {
          "alias": "int_bolt_core",
          "name": "int_bolt_core"
        },
        {
          "alias": "int_bolt_csc",
          "name": "int_bolt_csc"
        },
        {
          "alias": "int_bolt_extensions",
          "name": "int_bolt_extensions"
        },
    

    Running Multiple Hooks & Cartridges? Hooks are executed in the order their cartridges appear on the path; changing the order of the cartridges also changes the order of hook execution. Refer to Salesforce’s official documentation on SFRA Hooks for more information.

  4. Confirm that Bolt-specific changes from cartridges/int_bolt_sfra/cartridge/client/default/js/main.js have transferred to cartridges/<top-level cartridge of merchant>/cartridge/client/default/js/main.js.
  5. Remove both of the following:
    • cartridges/int_bolt_sfra/cartridge/static/default/js/main.js
    • cartridges/int_bolt_sfra/cartridge/client/default/js/main.js
  6. Recompile the js and scss for the changes to get reflected on your front end.

3. Upload

  1. Open Visual studio code.
  2. Navigate to Extensions.
  3. Search for and install prophet debugger.
  4. Open the folder containing your cartridges in VS Code.
  5. Navigate to File > Preferences > Settings.
  6. Search for extension.prophet.upload.enabled.
  7. Set this setting to true.
  8. Restart the Visual Studio Code window for the changes to take effect.
  9. Select the cloud icon > ellipses next to CARTRIDGES.
  10. Choose Prophet: Enable Upload.
  11. Open Business Manager in your browser.
  12. Navigate to Administration > Site Development > Code Deployment.
  13. Choose the version of the code you specified in the dw.json file.

Via CLI

  1. Navigate to the root directory and run npm run upload:all.
  2. Navigate to Administration > Site Development > Code Deployment.
  3. Choose the version of the code you specified in the dw.json file.

Configure Business Manager

1. Activate the Bolt Cartridge

  1. Log in to Business Manager.
  2. Navigate to Administration > Sites > Manage Sites > > Settings.
  3. Select the correct Instance Type from the dropdown.
  4. In the Cartridges input field, add int_bolt_sfra:int_bolt_csc:int_bolt_extensions:int_bolt_core in front of the base cartridge path.
  5. Select Apply.
  6. Repeat steps 2 to 6 if you have more storefronts that you would like to install Bolt on.
  7. Navigate to the Manage the Business Manager site.
  8. In the Cartridges input field, add bm_bolt:int_bolt_core .
  9. Select Apply.
  10. Select Site Status > Select the Site Status > Online.
  11. Select Apply.

2. Enable the Cartridge Module

  1. Navigate to Administration > Organization > Roles & Permissions.
  2. Select Administrator > Business Manager Modules.
  3. In the Select Context dialog, check your site’s checkbox and select Apply.
  4. Find Bolt and enable it.
  5. Select Update.

Import Required Metadata

For the Bolt integration to work, the following object structures (metadata) need to be imported and configured in the Business Manager.

  1. Open the cartridge bundle.
  2. Navigate to the metadata/Bolt-meta-import/Sites/RefArch folder.
  3. Rename the RefARch folder to be the same as the ID of your site. If you have multiple sites which require the metadata to be imported, then:
  4. Copy and paste the RefArch folder to replicate for other sites.
  5. Rename those folders with the ID of corresponding sites.
  6. Open the specific site folder and find the library folder.
  7. Edit the library/library.xml file to change the library-id mentioned in it. If your site uses a private library, then remove the library-id attribute and its value. If your site uses a shared library, then replace the existing library-id ‘RefArchSharedLibrary’ in the XML with your actual shared library-id.
  8. Save the library.xml file.
  9. In the cartridge bundle, inside the metadata folder, compress the Bolt-meta-import folder to generate the Bolt-meta-import.zip file.
  10. Navigate to Business Manager > Administration > Site Development > Site Import & Export.
  11. Under Import - Upload Archive, ensure that local is enabled.
  12. Select Choose File and select the Bolt-meta-import.zip file.
  13. Select Upload.
  14. After finishing the upload, navigate to the Archives list and select the radio button corresponding to Bolt-meta-import.zip.
  15. Select Import.
  16. Select OK from the confirmation box.

Custom Site Preferences

  1. Log in to Business Manager.
  2. Navigate to Merchant Tools > Site Preferences > Custom Preferences.
  3. Ensure the preference group with the ID Bolt Payment Setting is available.
  4. Select Bolt Payment Setting and edit the attributes according to your Bolt account data. For each site, set the values for your site preferences as follows below:
    • Enable Bolt Checkout: Boolean. Used to enable and disable Bolt payment in the site.
    • API Key: The merchant account identifier you want to process the (transaction) request with. Get this from Bolt.
    • Signing Secret: This is used to verify the authenticity of requests coming from Bolt. Get this from Bolt.
    • Publishable Key - Multistep: Used to get your account-specific value, get in touch with Bolt Account Manager.
    • Publishable Key - Back Office: Used to get your account-specific value, get in touch with Bolt Account Manager.
    • Display Bolt Checkout on the Cart Page: Boolean. Used to enable or disable the bolt checkout button on the cart page.
    • Display Bolt Checkout for BackOffice Payment: Boolean. Used to enable or disable the Bolt checkout button in Backoffice (Customer Service Center).
    • Display Bolt Checkout on the Native Checkout Page: Boolean. Used to enable or disable the Bolt checkout button on the native page.
    • Gift Certificate Enable: Boolean. Used to enable or disable gift certificate functionality.
    • Bolt Partner Merchant: String Enum. Used internally for Bolt to decide the merchant. Comes preset with default. Make sure it is not set to None.
    • Bolt Environment: String Enum. You can set it to either Sandbox or Production. Comes set with Production as default. Make sure it is not set to None.

Webhooks (Shipping & Tax)

1. Add API Endpoints

  1. Navigate to Administrator > Sites > Manage Sites and retrieve your site id.
  2. Log in to your Bolt Merchant sandbox.
  3. Navigate to Developers > API.
  4. Select Add Endpoint > Create order and set to the following:
    https://  {domain name}  /on/demandware.store/Sites-{site id}-Site/en_US/CreateOrder-Hook
    
  5. Select Add Endpoint > Shipping and Tax and set to the following:
    https:// {domain name} /on/demandware.store/Sites-{site id}-Site/en_US/ShippingTax-Hook
    

3. Add Webhook URLs

Reach out to your Customer Success Manager and request they set up the following URLs in the backend.

  1. Navigate to Developers > Webhooks.
  2. Select Add Endpoint and set to the following:
     https:// {domain name} /on/demandware.store/Sites-{site id}-Site/en_US/Webhook-V2
    
  3. Set the Shipping URL to the following:
    https://  {domain name}  /on/demandware.store/Sites-{site id}-Site/en_US/Shipping-Hook
    
  4. Set the Tax URL to the following:
    https://  {domain name}  /on/demandware.store/Sites-{site id}-Site/en_US/Tax-Hook
    
  5. Set the Update Cart URL to the following:
    https:// {domain name} /on/demandware.store/Sites-{site id}-Site/en_US/Webhook-V2
    

Optional Configurations

Enable Gift Card Support

  1. Navigate to Merchant Tools > Content > Content Assets.
  2. Find the footer-support content asset.
  3. Select the content asset ID. Lock the content asset to edit the content.
  4. Make the following changes to the Body input field:
    /// old <li><a href="#" title="Navigate to Gift Certificates">Gift Certificates</a></li> 
       
    
    /// new <li><a href="$httpsURL('GiftCert-Purchase')$" title="Navigate to Gift Certificates">Gift Certificates</a></li>
    
  5. Select Apply and Unlock the content asset.

Enable Apple Pay

  1. Navigate to Administration > Global Preferences > Global Custom Preferences.
  2. Select ApplePay in the custom preference group id.
  3. Set the ApplePay verification file in the Value field of the Apple Developer Merchant ID Domain Association.
  4. Select Apply.
  5. Navigate to Merchant Tools > SEO > Static Mappings and add the following:
    /.well-known/apple-developer-merchantid-domain-association.txt s,,,,,/.well-known/apple-developer-merchantid-domain-association.txt
    
  6. Navigate to Merchant Tools > SEO > Aliases and set aliases under the permanently redirected section using the format below:
    "your sandbox hostname”: [
            {
                   "http-host": " your sandbox hostname"
             }
      ]
    

Enable Ship to Store

  • All stores must have a custom attribute, shipToStoreEnabled, to indicate whether a store is available for Ship To Store
  • One shipping method must have the id ShipToStore. This is the shipping method for all stores. We currently do not support multiple shipping methods for Ship To Store functionality.
  1. Navigate to Merchant Tools > Online Marketing > Stores.
  2. Select the Store Name.
  3. Under FEATURES, set Ship To Store Enabled custom feature to Yes.
  4. Save.

Enable PLCC Promotion

Use Case 1

  1. Create a campaign and a promotion, tie the campaign and the promotion together by adding the promotion under Experience in the campaign page.
  2. Create a coupon code, tie it to the Campaign as well under Scheduling & Qualifiers
  3. Navigate to the coupon code config page, under General, set the number of redemption to 1 per user.

Use case 2

  1. Navigate to Merchant Tools > Ordering > Payment Methods.
  2. Create a payment method named BOLT_PLCC.
  3. Create a campaign and a promotion, tie the campaign and the promotion together by adding the promotion under Experience in the campaign page.
  4. Scroll to Scheduling & Qualifiers.
  5. Set the customer group to be everyone.
  6. Scroll to Promotion Rule.
  7. Set the Payment Method to be BOLT_PLCC.

Re-platforming

When re-platforming, you must keep in mind all of the following:

  • Use the Merchant Dashboard for order refunds. Do not use a platform-specific backoffice flow that’s connected to a deprecated account division.
  • Disable all of your old webhooks for the deprecated account division.

Final Notes

Roles

Bolt introduces no new roles with this integration. You must update existing roles to use the Business Manager extension with Bolt Transactions.

👎

How did we do?

📖On This Page