Integrate Purple Dot with Salesforce
Last updated
Last updated
The Purple Dot LINK cartridge allows you to quickly integrate a Purple Dot instance into a Salesforce Commerce Cloud website. Download the Purple Dot cartridge and unzip its contents:
The Purple Dot cartridge enables customers to make pre-orders for out-of-stock products on the merchant’s site. The Purple Dot cartridge provides next features on the SFCC platform:
Custom pre order button and cart elements on the storefront
Dedicated configuration page in Business Manager
Jobs which export and upload shipping methods, inventory lists and product catalogs to Purple Dot service
Refunds (full or partial)
The cartridge is designed for Salesforce Commerce Cloud API version 22.6 (Compatibility Mode: 21.7) with StoreFront Reference Architecture (SFRA) version 6.0.0. It also supports older SiteGenesis (SG) sites. The cartridge is designed for the US and GB locales, but can work with other locales.
Glossary
SFCC
Salesforce Commerce Cloud
Business Manager (BM)
The primary tool used to configure the SFCC platform and customer storefront SFRA
SFRA
StoreFront Reference Architecture
SG
SiteGenesis
Download the cartridge source code.
Establish a new digital server connection with your SFCC Instance.
Import cartridges to a workspace in Salesforce UX Studio.
Add cartridges to Project Reference of Server Connection.
For SFRA, add the int_purpledot
and int_purpledot_sfra
cartridges.
For SG, add the int_purpledot
, int_purpledot_controllers
, and purpledot_sg_changes
cartridges.
Wait until Studio completes workspace build and uploads source codes to the sandbox.
Go to Administration > Sites > Manage Sites
and select your site from the list of “Storefront Sites”.
Go to the Settings tab for your site.
For SFRA sites, in the beginning of the cartridge path add the following:
int_purpledot:int_purpledot_sfra:
Note: cartridge storefront_base
is the core SFRA cartridge, which must be present as default SFRA cartridge to run SFRA sites.
For SG sites, in the beginning of the cartridge path add the following:
purpledot_sg_changes:int_purpledot_controllers:int_purpledot:
Note: cartridges storefront_controllers
and storefront_core
are the core Controllers cartridges, which must be present as default Controller cartridges to run SG sites.
Go to Administration > Site Development > Site Import & Export
. Create a zip archive of the metadata
folder and upload metadata.zip.
Select metadata.zip and finish the import process.
After import is successfully done, you should see the Purple Dot Custom Site Preference Group in the Business Manager by going toAdministration > Merchant Tools > Site Preferences > Custom Site Preferences
.
From Administration > Merchant Tools > Site Preferences > Custom Site Preferences
, select Purple Dot.
The following preference values need to be set:
Enable PurpleDot
Enable/disable all Purple Dot instances across the site
API key
Value for Purple Dot SDK. Your API key can be retrieved from Purple Dot by going to Settings > Integration > API Keys.
Secret Key
Value for JSON Web Token generator. Your Shared Secret Key can be retrieved from Purple Dot by going to Settings > Integration > API Keys.
Button style
Custom CSS styles for the Purple Dot pre-order button element.
Cart style
Custom CSS styles for the Purple Dot cart button element.
There are three jobs that need to be set up:
PurpleDotCatalogExport
PurpleDotInventoryExport
PurpleDotShippingMethodsExport
Note: Catalog export job supports only one catalog at a time by default. If there is a need to upload more than one catalog, duplicate existing catalog export job and change its job ID to match the following pattern - PurpleDot_CatalogExportJob_<YOUR CUSTOM SUFFIX>.
The following steps are similar for all Purple Dot jobs. The specific steps for job marked with the name of this particular job:
Go to Administration > Administration > Operations > Job Schedules > [PurpleDot_CatalogExport/PurpleDot_InventoryExport/PurpleDot_ShippingMethodsExport].
Go to the Schedule and History tab in order to define job intervals. Your catalogs/inventory lists/shipping methods will be synced in the Purple Dot system each time jobs have been scheduled.
Go to the Job Step tab and click on the “Organization” button
Select needed site for every job step (Note: For the CreateCatalogFeed step in PurpleDot_CatalogExport job the only applicable scope is “Organization”)
[PurpleDot_ExportCatalog job] Open CreateCatalogFeed step, enter catalog ID to export in the “CatalogID” field and click the “Assign” button. (Note: Only “owned” products from catalog will be exported, “assigned” products will be ignored)
Go to Administration > Operations > Services > Credentials
. Choose purpledot.s3.aws.cred.
Enter service credentials provided by Purple Dot, setting the provided AWS access key as user and access secret as password.
Test that the jobs work by clicking Run Now.
Warning: If the jobs fails immediately or if the storefront isn't being updated, you might need to reactivate your current code version.
Warning: OCAPI permissions need to be appended in addition to any pre-existing permissions.
Enter OCAPI permissions within Business Manager: Administration > Site Development > Open Commerce API Settings
. See this “purpledot ocapi shop.json” file for required permissions.
The cartridge registers one hook-point to facilitate further customization:
The hook-point dw.ocapi.shop.order.afterPATCH is used to update payment status of the order placed with PurpleDot pre-order checkout
In your Purple Dot Merchant Portal, go to Settings > Integration > Connected SFCC Store and click Connect. Fill in the SFCC instance and site you are connecting to, the OCAPI Client ID and password, if using a sandbox instance the Sandbox username and password, and click save. Credentials will be validated upon saving.
Note: all changes are already made in the int_catch_sfra cartridge. Files in the current cartridge use scripts and utilities from core cartridges. The file paths inside require() functions were changed to keep the relative paths to the core cartridges.
For each of the following files, add the required code:
app_storefront_base/cartridge/templates/default/purpleDot/cartbutton.isml
If using the express checkout and a separate card, set enableCart
to false
:
window.PurpleDot.init({ apiKey: '...', enableCart: false });
app_storefront_base/cartridge/models/product/decorators/index.js
Add the following row to the exported object in line 31 to extend product model decorators:
app_storefront_base/cartridge/templates/default/common/htmlHead.isml
Add the following rows to line 32 to inject the Purple Dot SDK script and custom cartridge css styles to the page:
app_storefront_base/cartridge/templates/default/components/header/headermenu.isml
Put the following rows to the line 33 to add link to Purple Dot self-service widget to the header menu:
app_storefront_base/cartridge/templates/default/components/header/pageHeader.isml
Add the following rows at line 45 to add the Purple Dot “Cart button” element to the page header:
app_storefront_base/cartridge/templates/default/product/components/addToCartGlobal.isml
Wrap the button and input elements responsible for the native addAllToCart
button on the PDPs with product sets and product bundles with following rows in line 3 to insert the Purple Dot Pre-order button on the page:
app_storefront_base/cartridge/templates/default/product/components/addToCartGlobal.isml
Wrap the button and input elements responsible for the native addToCart
button on the PDP with following rows in line 3 to insert the Purple Dot Pre-order button on the page:
app_storefront_base/cartridge/templates/default/product/productTile.isml
Put the following rows to the line 21 to include pre-order label to the product tile:
app_storefront_base/cartridge/templates/default/product/components/quantity.isml
Wrap the template elements responsible for the quantity number selection on the PDP with following rows in line to hide the quantity selector when the Purple Dot cartridge is enabled and Pre-order button is shown on the page:
app_storefront_base/cartridge/client/default/js/product/detail.js
Put the following row to the line 3 to add import helper function to the client-side script:
Wrap native code responsible for update of the addToCart button in the updateAddToCart() function in the line 76 to replace change handling behavior of the addToCart button when cartridge is enabled:
app_storefront_base/cartridge/client/default/js/product/detail.js
Add the following row to the line 80 in the fillModalElement()
function to add custom function responsible for Purple Dot load script initialization on quickView
modal window open:
Add the following row to the line 153 in the updateAddToCart()
function to handle addToCart
button in the quickView
modal window when cartridge is enabled:
Note: all changes are already made in the purpledot_sg_changes cartridge. Files in the current cartridge use scripts and utilities from core cartridges. The file paths inside require() and importScript() functions were changed to keep the relative paths to the core cartridges .
app_storefront _controllers/cartridge/models/controllers/Product.js
Put the following rows to the show()function in line31 to check if product is configured and available for pre-order via PurpleDot service:
Put the following row in line 39 to send value from the productToRender variable to the template’s pipeline dictionary:
Put the following rows to the variation() function in line 220 to check if product’s variant is configured and available for preorder via PurpleDot service:
Extend object in getView() function with the following row in lines 238, 245, 253 to send value from the productToRender variable to the template’s pipeline dictionary:
app_storefront _core/cartridge/templates/default/components/header/header.isml
Add the following rows to line 51 at the bottom of file to add the Purple Dot “Cart button” element to the page header:
app_storefront _core/cartridge/templates/default/components/header/header.isml
Add the following rows to the line 45 at the bottom of file to add a link to Purple Dot’s self-service widget to the header menu:
app_storefront _core/cartridge/templates/default/components/header/htmlhead.isml
Add the following rows at the line 30 to include Purple Dot SDK script in the page header:
Add the following rows to the line 85 to add cartridge styles to the page header:
app_storefront _core/cartridge/templates/default/product/productcontent.isml
Add the following row to line 3 to add import helper function to the client-side script:
Wrap the block of the template responsible for “Add to cart” button with the following rows in line 226 to add the Purple Dot “Pre-order” button element on the PDP page:
app_storefront_core/cartridge/templates/default/product/producttile.isml
Add the following rows to the line 129 to add the “preorder label” element to the product tile component:
app_storefront_core/cartridge/templates/default/product/producttopcontentPS.isml
Wrap the form with the following rows in line 153 in the end of the file to add the Purple Dot “Pre-order” button element on the “bundle” product page:
app_storefront_core/cartridge/templates/default/product/components/productsetproduct.isml
Wrap the form with the following rows in line 73 in the end of the file to add the Purple Dot “Pre-order” button element on the “bundle” product page:
app_storefront_core/cartridge/templates/default/product/components/recommendations.isml
Add the following rows in line 47 to add the “pre-order label” element to the product tiles in the blocks with recommendations:
app_storefront_core/cartridge/js/pages/products/productSet.js
Put the following rows to the line 7 in the top of file to add the handleSoldoutButtonState() function responsible for keeping the “Sold out” button element disabled after page loads:
Put the following rows to the line 32 in the top of file to the updateAddToCartButtons() function to keep “Sold out” button element disabled after page loads for ‘bundle’ products:
Here are some additional client side APIs that can be used to customise the storefront experience
You can use the following code in your storefront to determine the number of preorder items that a shopper has added to their cart.
You can open the Purple Dot checkout using the following code
The Purple Dot client-side SDK emits the following events on the storefront.
PurpleDot:Ready
Emitted when the Purple Dot SDK is initialised and ready for use
PurpleDot:AddToCart
Emitted when the shopper has added a preorder item to their cart
The above APIs and events can be leveraged to build a custom preorder checkout button. The following is a simplified example:
Follow the steps below to validate that you have successfully installed the Purple Dot cartridge.
All cartridge components are located in "Merchant Tools > Site Preferences > Custom Site Preference > PurpleDot".
PurpleDot service needs to be enabled. Specify your PurpleDot Public Key and PurpleDot API Key.
Go to Merchant Tools > Products and Catalogs >Inventory.
Choose an inventory book assigned to the current site.
Go to the “Records” tab, find the product that should be configured and click the “Edit” button.
Configure the product’s availability settings by setting “Allocation” field value to 0.0 (zero).
Set the “None” checkbox in for the “Pre-Order/Backorder Handling” field.
Product Availability Status should change to Not Available.
Go to Administration > Operations > Jobs > [[PurpleDot_Job]]
Run each job by clicking the “Run now” button
Create a waitlist in the PurpleDot dashboard [Putting a Product on Pre-order]
Add configured product to the waitlist [From your Catalogue]
Configure and save a waitlist.
On the PDP page with the configured product the custom “Pre-order” button should appear.
After adding the configured product to the pre-order list, the custom Purple Dot cart icon should appear near the default storefront cart icon.
In the BM inventory data should change:
Pre-Order/Backorder Allocation: your data.
Availability Status: Pre-order.
Proceed to checkout by clicking the “Checkout” button.
The modal window with Purple Dot pre-order checkout should appear.
On the product tile of the configured product the “Pre-order” label should appear.
Click the “Pre-order history” link.
A new page with PurpleDot self-service widget should open.
Place an order using Purple Dot pre-order checkout. Go to the Purple Dot dashboard and find your pre-order in the “Pre-orders” tab. Click on the pre-order.
Export your pre-order to the SFCC by clicking the “Export pre-order to SFCC button”.
Click the “Refund payment” button.
Enter the refund amount and click the “Confirm refund” button.
Go to the BM: Merchant Tools > Ordering > Orders
and find order.
Check order notes. A note with the refund amount in the order’s “Notes” tab should appear in order notes.
Configure manual tax rate in Purple Dot -> Settings -> Taxes
or add your Vertex Key.
Login to the Purple Dot dashboard is via an email magic link of SSO. See separate documentation for SSO configuration.
If required, ask the Purple Dot team to enable the Clutch Gift Cards integration.
Download the full Purple Dot cartridge documentation: