# Integrate Purple Dot with Salesforce Start by signing up to Purple Dot as a Merchant. If you don't have a Merchant Account yet, send us an email at and we'll get you set up. ## Install the Purple Dot LINK cartridge 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: {% file src="" %} v22.1.0 Cartridge (SHA256 14825fc5698ecc1442f463ebf1cb5e666b085e038c43f30929050489d2bcfd9b) {% endfile %} 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**
TermDescription
SFCCSalesforce Commerce Cloud
Business Manager (BM)The primary tool used to configure the SFCC platform and customer storefront SFRA
SFRAStoreFront Reference Architecture
SGSiteGenesis
### Set Up Business Manager #### Import Purple Dot cartridges 1. Download the cartridge source code. 2. Establish a new digital server connection with your SFCC Instance. 3. Import cartridges to a workspace in Salesforce UX Studio.
4. Add cartridges to Project Reference of Server Connection. 1. For **SFRA**, add the `int_purpledot` and `int_purpledot_sfra` cartridges.
2. For **SG**, add the `int_purpledot`, `int_purpledot_controllers`, and `purpledot_sg_changes` cartridges.
5. Wait until Studio completes workspace build and uploads source codes to the sandbox. #### Assign cartridges to the site 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. #### Import metadata 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. ### Configure Site After import is successfully done, you should see the Purple Dot Custom Site Preference Group in the Business Manager by going to`Administration > Merchant Tools > Site Preferences > Custom Site Preferences`.
#### Set custom site preferences From `Administration > Merchant Tools > Site Preferences > Custom Site Preferences`, select **Purple Dot**.
The following preference values need to be set:
Preference nameDescription
Enable PurpleDotEnable/disable all Purple Dot instances across the site
API keyValue for Purple Dot SDK. Your API key can be retrieved from Purple Dot by going to Settings > Integration > API Keys.
Secret KeyValue for JSON Web Token generator. Your Shared Secret Key can be retrieved from Purple Dot by going to Settings > Integration > API Keys.
Button styleCustom CSS styles for the Purple Dot pre-order button element.
Cart styleCustom CSS styles for the Purple Dot cart button element.
### Set Up Jobs 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\_**\. The following steps are similar for all Purple Dot jobs. The specific steps for job marked with the name of this particular job: 1. Go to Administration > Administration > Operations > Job Schedules > \[PurpleDot\_CatalogExport/PurpleDot\_InventoryExport/PurpleDot\_ShippingMethodsExport]. 2. 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.
3. Go to the Job Step tab and click on the “Organization” button 4. Select needed site for every job step (**Note:** For the *CreateCatalogFeed* step in *PurpleDot\_CatalogExport job* the only applicable scope is “Organization”)
5. **\[*****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)
#### Provide Service Credentials 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. ### OCAPI settings **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. {% file src="" %} {% file src="" %} 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 ### Add Salesforce Commerce Cloud credentials to Purple Dot 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. ![](https://35070260-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F58PWmT9iYQoKNKYtPSZy%2Fuploads%2FhfcmzIjGwBZ1qjnt6kxF%2FScreenshot%202024-08-07%20at%2016.32.59.png?alt=media\&token=445a6842-64fa-463a-b026-5e348c8a7983) ## Integrate Purple Dot with your SFRA site ### Edit models **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: 1. **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 });` 2. **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: ```jsx pdProduct: require('*/cartridge/models/product/decorators/pdProduct') ``` 3. **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: ```html Purple Dot code Purple Dot code ``` 4. **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: ```html Purple Dot code Purple Dot code ```
5. **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: ```html Purple Dot code Purple Dot Cart Button PurpleDot code ```
6. **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: ```html Purple Dot code Purple Dot Preorder Button ... // template content goes here Purple Dot code ```
7. **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: ```html Purple Dot code Purple Dot Preorder Button ... // template content goes here Purple Dot code ```
8. **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: ```html Purple Dot code Purple Dot code ```
9. **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: ```html Purple Dot code ... // template content goes here ```
### Edit client-side scripts 1. **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: ```jsx // Purple Dot code var pdHelper = require('../purpleDot/helpers/pdHelper'); // Purple Dot code ```
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: ```jsx // Purple Dot code if (response.product.pdProduct.isEnabled) { pdHelper.handleAddToCartButton(response); } else { ... // client-side script content goes here } // Purple Dot code ```
2. **app\_storefront\_base/cartridge/client/default/js/product/detail.js** ```jsx // Purple Dot code var pdHelper = require('../purpleDot/helpers/pdHelper'); // Purple Dot code ```
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: ```jsx // Purple Dot code pdHelper.initializePurpleDotLoadScript(data); // Purple Dot code ```
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: ```jsx // Purple Dot code if (response.product.pdProduct.isEnabled) { pdHelper.handleAddToCartButton(response); } else { // ... client-script content goes here } // Purple Dot code ```
## Integrate Purple Dot with your SG site ### Edit controllers **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 .** 1. 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: ```jsx // PurpleDot code start var productToRender = require('*/cartridge/scripts/purpleDot/helpers/pdHelper').getProductToRender(product); // PurpleDot code end ``` Put the following row in line 39 to send value from the productToRender variable to the template’s pipeline dictionary: ```jsx productToRender: productToRender, // PurpleDot code ```
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: ```jsx // PurpleDot code start var productToRender = require('*/cartridge/scripts/purpleDot/helpers/pdHelper').getProductToRender(product); // PurpleDot code end ``` 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: ```jsx productToRender: productToRender, // PurpleDot code ```
### Edit templates 1. **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: ```html Purple Dot Cart Button ```
2. **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: ```html Purple Dot code Purple Dot self-service widget
  • ${Resource.msg('link.name.preorderhistory', 'purpledot', null)}
    • Purple Dot code ```
    3. **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: ```html Load the Purple Dot SDK ```
    Add the following rows to the line 85 to add cartridge styles to the page header: ```html ```
    4. **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: ```html Purple Dot // ...template content goes here Purple Dot ```
    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: ```html Purple Dot // ...contents of the template go here PurpleDot Preorder Button Purple Dot ```
    5. **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: ```html PurpleDot Pre-order label ```
    6. **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: ```html // contents of the core cartridge go here Purple Dot Preorder Button ```
    7. **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: ```html Purple Dot code // ...form content Purple Dot code ```
    8. **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: ```html PurpleDot Pre-order label ```
    ### Edit client-side scripts 1. **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: ```jsx // PurpleDot code function handleSoldoutButtonState() { var pdSoldoutButton = $('button.pd-sold-out'); if (pdSoldoutButton.length > 0) { pdSoldoutButton.prop('disabled', true); } } // PurpleDot code ``` 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: ```jsx // PurpleDot Code handleSoldoutButtonState(); // PurpleDot Code ```
    ### Additional client-side APIs Here are some additional client side APIs that can be used to customise the storefront experience #### numberOfPreorderItemsInBag You can use the following code in your storefront to determine the number of preorder items that a shopper has added to their cart. ```javascript window.PurpleDot.numberOfPreorderItemsInBag().then( (preorderItemsInBag) => { // ... } ); ``` #### openCheckout You can open the Purple Dot checkout using the following code ```javascript window.PurpleDot.openCheckout() ``` ### Events The Purple Dot client-side SDK emits the following events on the storefront. | Event name | Description | | ------------------- | ---------------------------------------------------------------- | | 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 | ### Building a custom preorder checkout button The above APIs and events can be leveraged to build a custom preorder checkout button. The following is a simplified example: {% code overflow="wrap" lineNumbers="true" %} ```html ``` {% endcode %} ## Test the Integration Follow the steps below to validate that you have successfully installed the Purple Dot cartridge. ### Business Manager \[Inventory Management] 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*. #### **Configure product** 1. Go to Merchant Tools > Products and Catalogs >Inventory. 2. Choose an inventory book assigned to the current site. 3. Go to the “Records” tab, find the product that should be configured and click the “Edit” button.
    4. Configure the product’s availability settings by setting “Allocation” field value to 0.0 (zero). 5. Set the “None” checkbox in for the “Pre-Order/Backorder Handling” field.
    Product Availability Status should change to **Not Available.** #### **Synchronize catalog and shipping methods with Purple Dot platform** 1. Go to Administration > Operations > Jobs > \[\[PurpleDot\_Job]]
    2. Run each job by clicking the “Run now” button
    #### **Create waitlist in the Purple Dot dashboard** 3. Create a waitlist in the PurpleDot dashboard \[Putting a Product on Pre-order]
    4. Add configured product to the waitlist \[From your Catalogue]
    5. Configure and save a waitlist.
    ### Storefront \[Visual Components – PDP, Checkout and Self Service] #### PDP 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.
    #### **Pre-order label** On the product tile of the configured product the “Pre-order” label should appear.
    #### **Self-service widget** Click the “Pre-order history” link.
    A new page with PurpleDot self-service widget should open.
    ### Other \[Refund, Taxes and SSO] #### **Refunds** 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. #### **Taxes** Configure manual tax rate in `Purple Dot -> Settings -> Taxes` or add your Vertex Key. #### **Login** Login to the Purple Dot dashboard is via an email magic link of SSO. See separate documentation for SSO configuration. #### **Gift Cards** If required, ask the Purple Dot team to enable the Clutch Gift Cards integration. ## Download Documentation Download the full Purple Dot cartridge documentation: {% file src="" %} v22.1.0 Docs {% endfile %}