Salesforce Storefront Reference Architecture 19.1.0

This document provides the guidelines for the implementation of the PowerReviews Storefront Reference Architecture (SRA) enabled cartridge to SalesForce Commerce Cloud (SFCC).

Component Overview

Functional Overview

This cartridge covers the following PowerReviews jobs: Reviews, Social Question and Answers.

Use Cases

Jobs

PowerReviews cartridge supports two optional jobs that may be imported from the provided metadata.

PowerReviews‑ExportOrders is a job that will gather all orders for a site by specified locale. The orders are packaged into a CSV file and exported via SFTP to PowerReviews.

PowerReviews‑ExportProducts is a job that gathers all the product within a site by specified locale. The products are packaged as a CSV file and exported via SFTP to PowerReviews.

IMPORTANT: In order to run these jobs, you must have specific values in the PowerReviews Custom Preferences and Service Credentials that will be given you by your PowerReviews Client Success representative.

Reviews

Write Review ‑ Go to the storefront and login or create a new account, then navigate to an individual product. On the product detail page, underneath the product name, you should see a Reviews Snippet. Click the “Write a Review” link. You should now be on a page with the Write a Review form. Fill out the form, click Preview, check the required checkboxes, and then click Submit. At this point, you’ve submitted a Review to PowerReviews for the selected product.

Read Reviews – Go to storefront and navigate to an individual product. On the product details page, scroll to the boom of the page or click the “Read Reviews” link. You should automatically be directed to the Reviews tab at the bottom of the page if you clicked the link. The Reviews tab should show a snapshot of the current reviews as well as list each Review’s details. If no Reviews have been submitted, you should see a prompt to write a review.

Social Questions & Answers

Ask Question – Go to storefront and navigate to an individual product. On the product detail page, underneath the product name, you should see a Q&A Snippet. Click the “Ask a Question” link. You should now be on a page with the Ask a Question form. Fill out the form, click Preview, check the required checkboxes, and then click Submit. At this point, you’ve submitted a Question to PowerReviews for the selected product.

Read Questions/Answers – Go to storefront and navigate to an individual product that has Questions in the PowerReviews system already. On the product detail page, scroll to the bottom of the page or Click the “X Quesons” or “X Answers” link in the Q&A Snippet. You should automatically be directed to the Q&A tab at the bottom of the page if you click either of the links. The Q&A tab should show a snapshot of the current questions and answers as well as a list of each question/answer. If no questions or answers have been submitted you should see a prompt to Ask a Question

Answer Question – Follow the steps above for “ Read Questions/Answers”, then click the "Answer this question" link for a specific question. You should now be on a page with the Answer Question form. Fill out the form, click Preview, check the required checkboxes, then click Submit . At this point, you’ve submitted an Answer to PowerReviews for the selected Question.

Seller Rating

Leave Shopping Experience Review: Go to the storefront and log in or create a new account, then navigate to an individual product. Add the product to your cart and click checkout. Follow the checkout steps filling out the forms and purchase the product. On the confirmation page, there should be a pop-up window with stars where the customer ccan leave their review on the shopping experience using the website. Fill out the form and click Submit Review. At this point, you've submitted a Seller Rating to PowerReviews, connected with your own shopping experience.

Multiple Sites/Locales

The PowerReviews LINK cartridge supports multiple Sites and multiple languages/locales within those Sites. The PowerReviews‑ExportProducts job can be set to run for multiple Sites. Additionally, in the Job configuration, the locale for export can be specified as a job parameter. If not specified the Site default locale will be used. Multiple job steps (or separate jobs) may be configured to support additional site locales.

Limitations, Constraints

With Release 17.0. job schedules are optional. Job steps and an example jobs import are provided to support exporting orders and exporting catalog data. These functions are also performed dynamically online as each product is viewed and order is placed. Consult with you PowerReviews representave for guidance on when these might be needed. Job schedule for order feed should be configured in appropriate way. Recommended schedule has been written in the Business Manager section of the User Guide on this page. If the job is not correctly configured orders data will not be processed by PowerReviews.

Compatibility

Built on Commerce Cloud 19.6 (Compatibility Mode 18.10) and Storefront Reference Architecture 4.1.0.

Privacy and Payment

There are currently no privacy or payment issues.

Implementation

Setup

The following PowerReviews integration tasks are included within the LINK Cartridge:

  • Installation of the cartridge
  • Import custom metadata
  • Set the newly-created metadata values (Site Preferences).
  • Import or create Product and Order feed job(s).
  • Make storefront cartridge edits

Configuration

  1. Import the int_powerreviews_sfra cartridge into the Commerce Cloud Studio Workspace:

    1. Open Commerce Cloud Studio.
    2. Click File > Import > General > Existing Projects into Workspace.
    3. Browse to the int_powerreviews_sfra directory.
    4. Click Finish.
    5. Click OK when prompted, to link the cartridge to the sandbox.
  2. Assign cartridge to site:

    1. Log into Business Manager.
    2. Click Administration > Sites > Manage Sites > MobileFirst or required site.
    3. Select the Settings tab.
    4. Add int_powerreviews_sfra to the beginning of the cartridge path (or ensure it is in front of app_storefront_base as shown in the following figure).

  1. Re-activate the current code version (on sandboxes).

    This may be necessary to ensure the custom job steps are available.

    1. Click Administration -> Site Development -> Code Deployment.
    2. Activate a different code version from the current.
    3. Activate the desired code version.

Import Metadata

The metadata_sfra directory is in Site/Import Export format and may be zipped and uploaded through that interface. This may be uploaded and imported via Administration > Site Development > Site Import & Export which will complete all the steps in this section (3.2.1) at once.

  1. Metadata:

    1. Select Administration > Site Development > Site Import & Export.
    2. Click Upload.
    3. Browse for the metadata/metadata_sfra/meta/system-objecttype-extensions.xml and metadata/meta/custom-objecttype-extensions.xml files.
    4. Click Upload for each file.
    5. Click the << Back button.
    6. Under Meta Data, click Import.
    7. Select the system-objecttype-extensions.xml file.
    8. Click Next.
    9. When validation is complete, click Next to import.
    10. Repeat the Import process for custom-objecttype-extensions.xml.
  2. (Optional) Import Job Samples:

    1. Select Administration > Operations > Import & Export.
    2. Upload metadata_sfra/jobs.xml.
    3. Under Job Schedules, click Import.
    4. Import the uploaded jobs.xml file.
    5. Configure Jobs, which are described in section 5.2 (User Guide, Business Manager) of the Technical Cartridge Documentation document.
  3. Import Services (only necessary to support jobs).

    1. Select Administration > Operations > Import & Export.
    2. Upload the metadata_sfra/services.xml file.
    3. Under Services, click Import.
    4. Import the uploaded services.xml file.
    5. Configure the Service Credentials given to you by PowerReviews.

Custom Site Preferences

  1. Configure PowerReviews Custom Site Preferences using commerce Cloud Business Manager.

    1. Select Site Preferences > Custom Preferences > PowerReviews for each site you wish to configure.
    2. Enter thee appropriate values (see the "Business Manager" section for a description of each setting).
    3. Click Apply near the bottom of the page.
  2. Perform a regression test to ensure the site is still functional.

Custom Code

No custom code is necessary as the cartridge overlays with SFRA and implements the necessary templates and controller enhancements for all functionality.

However customization of these templates may be desired or necessary for the integration into storefront overlay cartridges. A listing of the custom templates with descriptions follows. Any and all of these templates may be copied from the cartridge into storefront overlay cartridges for customization (or alternatively used as a reference for storefront customization).

  • product/productTileFooter.isml

    • This overrides the SFRA tile footer to make room for reviews summary rendering
  • product/components/ratings.isml

    • This overrides the SFRA ratings on the product tiles for reviews summary rendering
  • product/components/productRating.isml

    • This overrides the SFRA ratings block on the PDP for rendering of reviews and Q&A summaries and links
  • product/components/descriptionAndDetails.isml

    • This overrides the stock SFRA description and details block at the bottom of the PDP to make room for reviews rendering.
  • product/components/reviews.isml

    • This renders the necessary blocks and inline scripts to render the reviews and Q&A on the PDP
  • powerreviews/writereview.isml

    • This is used by the custom controller action PowerReviews-WriteReviewPage to render the write review page.
  • checkout/confirmation/confirmationDetails.isml

    • This overrides the SFRA confirmationDetails on the confirmation page for rendering Seller Rating pop-up window.

Note to the System Integrator

This document is for integration of PowerReviews into the Storefront Reference Architecture (SRA). Specifically version 2.1.0.

There are two known instances where the provided reviews customization of the SiteGenesis styles are not sufficient:

  • When selecting "read review" on the PDP of a product that has at least one review, the page scrolls to the tab section at the bottom but fails to select the reviews tab.
  • When the review section is displayed, the expanded display extends beyond the fixed page footer.

Both issues are a result of the way SiteGenesis has styled the tab content container and footer. Addressing this issue requires changing and/or adding core SiteGenesis functionality; since this is a normal part of the necessary customization for each site, it is left as a customization task for the system integrator.

External Interfaces

PowerReviews requires that you are able to successfully connect to their servers using SFTP. All you need to do is to get the PowerReviews-provided SFTP credentials for your specific account. The SFTP credentials are used when setting up the Job Service. See the Business Manager section for more information on Configuration.

Testing

Reviews

Write Review - Go to storefront and log in or create a new account, then navigate to an individual product. On the product detail page, underneath the product name, you should see a Reviews Snippet. Click the "Write a Review" link. You should now be on a page with the Write-a-Review form. Fill out the form, click Preview, check the required checkboxes, then click Submit. At this point, you've submitted a Review to PowerReviews for the select for the selected product.

Read Review - Go to storefront and navigate to an individual product. On the product details page, scroll to the bottom of the page or click the "Read Reviews" link. You should automatically be directed to the Reviews tab at the bottom of the page. The Reviews tab should show a snapshot of the current reviews as well as list each Review's details. If no Reviews have been submitted, you should see a prompt to write a review.

Social Questions and Answers

Ask a Question - Go to storefront and navigate to an individual product. On the product detail page, underneath the product name, you should see a Q&A Snippet. Click the "Ask a Question" link. You should now be on a page with the Ask a Question form. Fill out the form, click Preview, check the required checkboxes, then click Submit. At this point, you've submitted a Question to PowerReviews for the selected product.

Read Questions/Answers - Go to storefront and navigate to an individual product that has Questions in the PowerReviews system already. On the product detail page, scroll to the bottom of the page or click "X Questions" or "X Answers" link in the Q&A Snippet. You should automatically be directed to the Q&A tab at the bottom of the page if you click either of the links. The Q&A tab should show a snapshot of the current questions and answers as well as a list of each question/answer. If no questions or answers have been submitted, you should see a prompt to Ask a Question.

Answer Question - Follow the steps above for "Read Questions/Answers", then click click the "Answer this question" link for a specific question. You should now be on a page with the Answer Question form. Fill out the form, click Preview, check the required checkboxes, then click Submit. At this point, you've submitted an Answer to PowerReviews for the selected Question.

Seller Rating

Leave Shopping Experience Review: Go to the storefront and log in or create a new account, then navigate to an individual product. Add product to the cart and click checkout. Follow the checkout steps filling out the forms and purchase the product. Add product to the cart and click checkout. Follow the checkout steps filling out the forms and purchase the product. On the confirmation page, there should be a pop-up window with stars where the customer can leave their review on the shopping experience using the website. Fill out the form and click Submit Review. At this point, you've submitted a Seller Rating to PowerReviews connected with your own shopping experience.

Multiple Sites/Locales

Go to the storefront and navigate to an individual product that you know has Reviews in two or more different languages/locales. Scroll down to view the Review content. You should see the content being displayed in the normal locale/language. To manually change the rendered locale, go to your browser address bar and find the locale id in the URL (for example: "en_US"). Replace that locale id with a different locale id (for example: "fr_CA"). Load the page with the new clocale and you should see that the review content (as well as the Q&A content) has been changed to account for the language change. Repeat this step on multiple Sites if appropriate, always ensuring that the Review/Q&A content is both locale and site-specific.

Operations, Maintenance

Data Storage

Site Preferences - the SitePrefences system object has been extended to store setup and confirmation values for each Demandware site.

Products - the Product system object has been extended to store product-specific data for reviews and question/answer templates.

Availability

This integration should work as expected as long as PowerReviews itself is up and running.

The exportOrder job and the exportProduct job are optional but may be scheduled as required either individually or as part of the PowerReviewsFullProcess job.

Support

For post live support please support a ticket via the PowerReviews portal or dashboard.

User Guide

Roles, Responsibilities

There are no recurring tasks that need to be fulfilled to get the full potential of PowerReviews other than the scheduled Jobs (see the Business Manager section below). As long as the configuration details are correct iny our Site Preferences, that is all you'll need to do.

Business Manager

Site Preferences Configuration

Configuration is stored in Custom Site Preferences. You may edit it in Business Manager by choosing your site, clicking Site Preferences in the left sidebar, clicking Custom Preferences in the body (bottom-right), then clicking the PowerReviews link.

Preference Configuration Description

PowerReviews Online Status

An on/off toggle for PowerReviews integration.

API Key This is a setting you will receive from PowerReviews.
PowerReviews GroupID This is a setting that you will receive from PowerReviews.
Default Catalog ID for the site The name of the default catalog for this specific site. To find out the catalog id click "Product and Catalogs" in the left nav of BM -> Catalogs -> then look for the string value in the ID column for the catalog that has been assigned to this specific site. For example: "storefront-catalog-en".
PowerReviews Sign in Requirement Provide Write Review/Questions/Answers functionality for non-authorized customers.
PowerReviews Order Feed File Name Use "orderFeed" as the base of the name, followed by an underscore and then your business name. If you have multiple Sites, please append an underscore and the Site Name to the file name. Example: "orderFeed_MySite_SiteGenesis".
PowerReviews Product Feed File Name Use "productFeed" as the base of the name, followed by an underscore and then your business name. If you have multiple Sites, please append an underscore and the Site Name to the file name. Example: "productFeed_MySite_SiteGenesis".
PowerReviews Locale Configs Allows you to configure locale mapping between DW locales and PowerReviews account.
PowerReviews Default Locale The default locale of the site. If not configured, then en_US value is used.
Seller Rating Widget Type The type of pop-up window on the confirmation page to leave customer experience review.
PowerReviews Seller Rating Locale configs Configure locale mapping between DW locales and PowerReviews account. This configuration is used for Seller Rating widget only.
PowerReviews Seller Rating API Key This is a setting you will receive from PowerReviews. This configuration is used for Seller Rating widget only.
PowerReviews Seller Rating Merchant GroupId This is a setting you will receive from PowerReviews. This configuration is used for Seller Rating widget only.
PowerReviews Seller Rating PageId This is a setting that you will receive from PowerReviews. This configuration is used for Seller Rating widget only.

Site Locale Configuration

Each locale can be configured with the appropriate pattern:

[DW_Locale]|[PowerReviews_Merchant_Id]

Example of correct configuration:

The following configuration steps are optional. If you are unsure about whether or not to do this, please contact PowerReviews.

Setup of the PowerReviews LINK cartridge requires creating two scheduled Jobs in Business Manager. To schedule a Job, go to Business Manager -> Administration -> Operations -> Job Schedules -> New. Create the following Jobs:

If you imported the example metadata in Custom Site Preferences, it already contains the jobs and only site and service configuration is required.

PowerReviews-ExportProducts

  • Name: PowerReviews-ExportProducts
  • Enabled: true
  • Execution Scope: Sites
  • Step Type: custom.powerreviews.ExportProducts
  • Schedule: The schedule of this job will be dependent on how often your product data changes. If it rarely changes, you can just run this job manually whenever it's necessary. If your product data is constantly changing, schedule this job accordingly.
  • Click the Sites tab and check the checkbox for each Site you'd like to run PowerReviews for. Click Apply.

This job should be setup on the Production environment. The Product Feed data is environment-dependent. For example, if you run this Job from Production, the product URLs that are exported will be Production product URLs.

PowerReviews-ExportOrders

  • Name: PowerReviews-ExportOrders
  • Enabled: true
  • Execution Scope: Sites
  • Step Type: custom.powerreviews.ExportOrders
  • Schedule: Initial run should be run manually for initialization inner timer. Further execution of this job should be configured in appropriate way. Recommended scheduling of this job is twice a week.
  • Click the Sites tab and check the checkbox for each Site you'd like to run PowerReviews for. Click Apply.

This job should be setup on the Production environment. The Product Feed data is environment-dependent. For example, if you run this Job from Production, the product URLs that are exported will be Production product URLs.

Services

If you imported the example metadata from the Configuration section on this page, you only need to configure the services.

  • Under Administration -> Operations -> Services, create or update the service powerreviews.stfp
  • Create or update the Service Credential specifying th enecessary SFTP URL, username, and password.

Storefront Functionality

The PowerReviews LINK cartridge adds reviews as well as social question/answer functionality to your storefront. Typically, this functionality is added to the product detail pages, category pages, and search pages (product girds).

Known Issues

SiteGenesis does not inherently provide a method of expanding tab content containers accessed by an anchor link on the product detail page.

This is part of the necessary customization by each merchant in applying distinct styles and behavior for each site implementation beyond the scope of Site Genesis.

Release History

Version Date

Changes

1.0.0 5/15/2012 Initial release
15.1.0 1/21/2015

Certification updates. Refactoring.

New functionality:

  • Analytics Beacon
  • Review Accelerator
  • Trigger file
  • Default locale
  • Category and search page review snippets
  • Async load of snippet/display
  • Product Variation controller
  • Write Review/Question and Answers for not sign in customers
15.2.0 4/24/2015 Implementing multi-locale support for each single DW site
16.1 4/14/2016

Certification updates. Refactoring:

  • BugGix on PDP due to platform changes
  • Adapt cartridge to 10X SiteGenesis code styles
  • Implement latest Cascading Style Sheets (CSS) styling
16.2.0 8/25/2016 Job optimization, implementing compatibility with sites based on controllers development model
18.1.0 1/16/2018 Converted cartridge to use JavaScript controllers and new PowerReviews display.
18.2.0 3/16/2018 Refactored cartridge and jobs for Storefront Reference Architecture and modern jobs framework.
19.1.0 5/15/2019 Bug fix of product info structure on PDP and checkout pages, add Seller Rating functionality.

Need more help? Contact us!