SFCC V1 Installation Guide
NOTE
This guide contains instructions for installing the legacy version of Bolt’s Salesforce integration. See SFCC V2 if you’ve recently signed up for Bolt.
Before You Start
- 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
-
Download the cartridge files sent by your Customer Success Manager.
-
Rename the .zip file to
bolt-demandware
. -
Unzip the
bolt-demandware
folder. -
Run the following:
npm install json json -I -f package.json -e "this.paths.base='<PATH TO APP_STORE_FRONT_BASE>'"
-
In the root directory, run the following:
npm ci
-
Navigate to the directory that contains all of your Bolt cartridges.
-
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
-
Place all Bolt cartridges in your storefront’s cartridge folder.
-
Open your storefront’s
package.json
file and locate“sites”: { “cartridges”: […] }
. -
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" },
WARNING
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.
- Confirm that Bolt-specific changes from
cartridges/int_bolt_sfra/cartridge/client/default/js/main.js
have transferred tocartridges/<top-level cartridge of merchant>/cartridge/client/default/js/main.js
. - 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
- Recompile the
js
andscss
for the changes to get reflected on your front end.
3. Upload
Via VS Code (Recommended)
- Open Visual Studio Code (VS Code).
- Navigate to Extensions.
- Search for and install
prophet debugger
. - Open the folder containing your cartridges in VS Code.
- Navigate to File > Preferences > Settings.
- Search for
extension.prophet.upload.enabled
. - Set this setting to
true
. - Restart the VS Code window for the changes to take effect.
- Select the cloud icon > ellipses next to CARTRIDGES.
- Choose Prophet: Enable Upload.
- Open Business Manager in your browser.
- Navigate to Administration > Site Development > Code Deployment.
- Choose the version of the code you specified in the
dw.json
file.
Via CLI
- Navigate to the root directory and run
npm run upload:all
. - Navigate to Administration > Site Development > Code Deployment.
- Choose the version of the code you specified in the
dw.json
file.
Configure Business Manager
1. Activate the Bolt Cartridge
- Log in to Business Manager.
- Navigate to Administration > Sites > Manage Sites >
> Settings. - Select the correct Instance Type from the dropdown.
- 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. - Select Apply.
- Repeat steps
2
to6
if you have more storefronts that you would like to install Bolt on. - Navigate to the Manage the Business Manager site.
- In the Cartridges input field, add
bm_bolt:int_bolt_core
. - Select Apply.
- Select Site Status > Select the Site Status > Online.
- Select Apply.
2. Enable the Cartridge Module
- Navigate to Administration > Organization > Roles & Permissions.
- Select Administrator > Business Manager Modules.
- In the Select Context dialog, check your site’s checkbox and select Apply.
- Find Bolt and enable it.
- 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.
- Open the cartridge bundle.
- Navigate to the
metadata/Bolt-meta-import/Sites/RefArch
folder. - 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: - Copy and paste the
RefArch
folder to replicate for other sites. - Rename those folders with the ID of corresponding sites.
- Open the specific site folder and find the library folder.
- Edit the
library/library.xml
file to change thelibrary-id
mentioned in it. If your site uses a private library, then remove thelibrary-id
attribute and its value. If your site uses a shared library, then replace the existinglibrary-id
‘RefArchSharedLibrary’
in the XML with your actual sharedlibrary-id
. - Save the
library.xml
file. - In the cartridge bundle, inside the metadata folder, compress the
Bolt-meta-import
folder to generate theBolt-meta-import.zip
file. - Navigate to Business Manager > Administration > Site Development > Site Import & Export.
- Under Import - Upload Archive, ensure that local is enabled.
- Select Choose File and select the
Bolt-meta-import.zip
file. - Select Upload.
- After finishing the upload, navigate to the Archives list and select the radio button corresponding to
Bolt-meta-import.zip
. - Select Import.
- Select OK from the confirmation box.
Custom Site Preferences
- Log in to Business Manager.
- Navigate to Merchant Tools > Site Preferences > Custom Preferences.
- Ensure the preference group with the ID Bolt Payment Setting is available.
- 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:
Attribute | Datatype | Description |
---|---|---|
Enable Bolt Checkout | Boolean | Used to enable and disable Bolt payment in the site. |
API Key | String | The merchant account identifier you want to process the (transaction) request with. Get this from the [Developers tab in Bolt’s Merchant Dashboard][1] |
Signing Secret | String | This is used to verify the authenticity of requests coming from Bolt. Get this from the [Developers tab in Bolt’s Merchant Dashboard][1]. |
Publishable Key - Multi-step | String | Opens the Bolt Payment Popup typically on Shopping cart and product pages. The publishable key is a long string of lower and upper case letters and numbers that consists of three sections. Get this from the [Developers tab in Bolt’s Merchant Dashboard][1]. Be sure to use the Dashboard Division configured for Multi-step checkout. |
Publishable Key - Back Office | String | Used in the back office of Magento for manually-created orders. Be sure to use the Dashboard Division configured for Back Office Orders. |
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 Back Office Payment | Boolean | Used to enable or disable the Bolt checkout button in Back Office (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. Default value set to Production . Make sure it is not set to None . |
Webhooks (Shipping & Tax)
1. Add API Endpoints
-
Navigate to Administrator > Sites > Manage Sites and retrieve your site id.
-
Log in to your Bolt Merchant sandbox.
-
Navigate to Developers > API.
-
Select Add Endpoint > Create order and set to the following:
https:// {domain name} /on/demandware.store/Sites-{site id}-Site/en_US/CreateOrder-Hook
-
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
NOTE
Reach out to your Customer Success Manager and request they set up the following URLs in the backend.
-
Navigate to Developers > Webhooks.
-
Select Add Endpoint and set to the following:
https:// {domain name} /on/demandware.store/Sites-{site id}-Site/en_US/Webhook-V2
-
Set the Shipping URL to the following:
https:// {domain name} /on/demandware.store/Sites-{site id}-Site/en_US/Shipping-Hook
-
Set the Tax URL to the following:
https:// {domain name} /on/demandware.store/Sites-{site id}-Site/en_US/Tax-Hook
-
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
-
Navigate to Merchant Tools > Content > Content Assets.
-
Find the
footer-support
content asset. -
Select the content asset ID. Lock the content asset to edit the content.
-
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>
-
Select Apply and Unlock the content asset.
Enable Apple Pay
-
Navigate to Administration > Global Preferences > Global Custom Preferences.
-
Select ApplePay in the custom preference group id.
-
Set the ApplePay verification file in the
Value
field of the Apple Developer Merchant ID Domain Association. -
Select Apply.
-
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
-
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.
- Navigate to Merchant Tools > Online Marketing > Stores.
- Select the Store Name.
- Under FEATURES, set Ship To Store Enabled custom feature to
Yes
. - Save.
Enable Subscriptions with Ordergroove
Ordergroove and Bolt have partnered so you can offer subscriptions to your shoppers. For information about how to set up the Ordergroove integration in SFCC, see Ordergroove. Talk to your Ordergroove CSM for more info about enablement and pricing.
Enable PLCC Promotion
Use Case 1
- Create a campaign and a promotion, tie the campaign and the promotion together by adding the promotion under Experience in the campaign page.
- Create a coupon code, tie it to the Campaign as well under Scheduling & Qualifiers
- Navigate to the coupon code config page, under General, set the number of redemption to
1
per user.
Use case 2
- Navigate to Merchant Tools > Ordering > Payment Methods.
- Create a payment method named
BOLT_PLCC
. - Create a campaign and a promotion, tie the campaign and the promotion together by adding the promotion under Experience in the campaign page.
- Scroll to Scheduling & Qualifiers.
- Set the customer group to be
everyone
. - Scroll to Promotion Rule.
- 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.