Salesforce Integration Guide

Suggest Edits

✉️

New to ShoppingGives?

If you are new to ShoppingGives, please reach out to our team of social impact specialist to learn more about our partnership packages. A subscription to our services is required to gain access to credentials required to integrate SFCC. You can learn more about our pricing at https://www.shoppinggives.com/pricing or you can schedule time by filling out the form below!

👍

Who should read this:

The webmaster or developer with HTML/CSS -level access to the e-commerce website.

Pre-Integration

The Salesforce Commerce Cloud integration requires the following:

  1. ShoppingGives Headless Widgets integration.
  2. A store ID and AWS Credentials from ShoppingGives to set up the cartridge. Please request these keys from your ShoppingGives representative.

Supported Architectures

ShoppingGives cartridge includes SFCC's reference architectures SiteGenesis and Storefront Reference Architecture (SFRA). SFRA is the more recent architecture, so if you are new to Salesforce Commerce Cloud, it is recommended that you build your site on this architecture.

Initial Cartridge Installation (Tutorial@00:47)

The following steps are required to install the ShoppingGives link cartridge:

  1. Install the cartridge into the SFCC
  2. Import the custom metadata
  3. Set the newly-created metadata values (see Site Preferences)
  4. Import or create the Product and Order feed jobs
  5. Make storefront cartridge edits:
    • Configure parameters
    • Import the int_shoppinggives_sg cartridge into the Commerce Cloud Studio Workspace:
      a) Open the Commerce Cloud Studio
      b) Click File -> Import -> General -> Existing Projects Into Workspace
      c) Browse to select the int_shoppinggives_sg folder directory
      d) Click Finish.
      e) Click OK when prompted to link the cartridge to the sandbox

Assign Cartridge to Business Manager

  1. Log into the Business Manager
  2. Click Administration -> Sites -> Manage Sites -> Business Manager Site
  3. Select the Settings tab
  4. Add int_shoppinggives settings variable with the beginning of the cartridge path value, click Apply
  5. Assign the cartridge to your desired site (sandbox, ...)
  6. Log into Business Manager
  7. Click Administration -> Sites -> Manage Sites -> SiteGenesis or the desired site
  8. Select the Settings tab and add int_shoppinggives_sg, int_shoppinggives_sg_changes, bm_shoppinggives, and int_shoppinggives variables to the beginning of the cartridge path (or ensure it is in front of app_storefront_base)

Configure ShoppingGives Preferences

In Business Manager, navigate to the target Site > Site Preferences > Custom Preferences.

Select the site preference group with the ID ShoppingGivesConfigs and edit it with the following parameters:

  • Preference Name Description
  • ShoppingGives Enabled Toggle on/off ShoppingGives integration
  • ShoppingGives S3 Access Key
  • ShoppingGives S3 Secret Key
  • ShoppingGives Store ID ShoppingGives Store ID
  • ShoppingGives S3 Bucket ShoppingGives S3 Bucket
  • ShoppingGives S3 Region ShoppingGives S3 Region
  • ShoppingGives Order
  • Export Status to Export
  • ShoppingGives Order Statuses to Export. See the description below.
  • ShoppingGives Last Order Sync
  • Specifies the date from which we need orders in the job
  • ShoppingGives Last Product Sync
  • Sets the date from which we need the product in the job
  • ShoppingGives ProductAssociated Groups ID, ShoppingGives attribute ID for associated groups ID, can be a product-level custom or system attribute. See the description below.
  • ShoppingGives ProductTags ID, ShoppingGives attribute ID for tags ID, can be a product-level custom or system attribute. See the description below.

Parameter: Order Export Status to Export

The order export status to export parameter will export orders with the export status configured in ShoppingGivesOrderExportStatustoExport in the custom preferences section.

The following values are the allowed statuses:

  • EXPORT_STATUS_EXPORTED
  • EXPORT_STATUS_FAILED
  • EXPORT_STATUS_NOTEXPORTED
  • EXPORT_STATUS_READY

📘

Info

For more information visit B2C documentation

Parameter: Product Associated Group ID and Product Tags ID

In order to take advantage of ShoppingGives Associated Groups and Tags it is necessary to map the corresponding attributes from a Product.

In Business Manager, navigate to the target Site > Site Preferences > Custom Preferences.

Select the site preference group with the ID ShoppingGivesConfigs

To map a ShoppingGives Product Associated Group Id or Product Tag Id, add the desired property Id into the corresponding value

Configure ShoppingGives Service Credentials

Importing the services.xml metadata file will create many ShoppingGives services, profiles,
and credentials. Verify that the following exists.

  • Services:
  • Profiles:
  • Service Credentials are required to be updated with the information provided by your ShoppingGives
    representative.
    • For S3 Region and Credentials, contact the ShoppingGives support portal.

Custom Code Configuration

The int_shoppinggives_sg_changes cartridge includes a default template for ShoppingGives located in int_shoppinggives_sg_changes\cartridge\templates\default\checkout\confirmation\confirmati on.isml.

If you have customized the template, you must merge it into your cartridge(s) and override the highlighted sniped code into your updated app_storefront_base cartridge’s confirmation.isml template.

Data Storage

Site Preferences – the SitePreferences system object has been extended to store the setup and confirmation values for each B2C Commerce site.

Availability

Out of the box and after the integration, the SFCC cartridge will provide automatic resync jobs to update the ShoppingGives Cause Stack backend and provide the expected behavior for consumers. There are two additional optional jobs named exportOrder and exportProduct that may be scheduled individually.

Failure/Recovery Process

When the cartridge is down, orders and products will not be exported. This will not operationally affect the storefront.

Roles/Responsibilities

No recurring tasks need to be fulfilled to get the full potential of ShoppingGives other than the scheduled Jobs. This is the extent of what is required if the configuration details are correct in your Site Preferences.

Staging vs. Production

Credentials have to be changed in the cartridge to point to the desired environment.

Make sure to connect with your ShoppingGives representative to get the correct credentials.

Technical Notes

Compatibility

ShoppingGives compatibility mode is 22.7, and the Site Genesis version is 105.2.1

Jobs

ShoppingGives cartridge supports four optional jobs that are imported in the metadata:

  • OrdersFeedExportFull is a job that will gather all orders for a site.
  • OrdersFeedExportDelta is a job that will collect all orders after the date of the last order feed job for a site.
  • ProductsFeedExportFull is a job that gathers all the products within the site.
  • ProductsFeedExportDelta is a job that will collect all products after the date of the last product feed job for a site.

📘

Info

Each process as described above packages its data as an XML file.

Here's some documentation for B2C from SalesForce

📘

Re-activate the current code version in sandboxes

Re-activating the current code version in sandbox enviroments may be necessary to ensure the custom job steps are available. To do so, click Administration > Site Development > Code Deployment Activate and select the updated version.

Website Widgets

Please refer to our Headless Widget Integration Guide

Updated 10 months ago