Salesforce Link Integration 19.1.0

This document provides the guidelines for the implementation of the PowerReviews Controllers enabled cartridge to SalesForce Commerce Cloud (SFCC).

This document describes the various components: Reviews, Social Questions, and Answers.

Component Overview

Functional Overview

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

Use Cases

Jobs

PowerReviews cartridge supports two optional jobs that are imported in the metadata.

ExportOrdersController is a job that will gather all orders for a site by locale. The orders are packaged as an XML file and exported via SFTP to PowerReviews.

ExportProductsController is a job that gathers all the product within a site by specific locale. The products are packaged as an XML file and exported via STP to PowerReviews.

In order to run these jobs, you must have specific values in the PowerReviews Custom Preferences that will be given to you by your PowerReviews Client Success Director.

Reviews

  • Write Review - Go to the 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. Clck the "Write a Review" link. You should now be on a page with a 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 the 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 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 and Answers

  • Ask Question- Go to the 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 fom. 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 the 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 pag eor click the "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 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 Questions form. Fill out the form, click Preview, check the required checkboxes, then click Submit. At this point, you've submitted and Answer to PowerReviews for the selected Question.

Seller Ratings

  • Leave Shopping Experience Review - Go to the storefront and login 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. On the confirmation page, there should be a pop-up window with stars where customer can leave his/her 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. Both the PowerReviewsProductFeed Job and the PowerReviewsFullProcess Job can be set to run for multiple Sites. Additionally, during each Job, each locale that has been activated in Business Manager will be accounted for assuming correct locale id mapping between SFCC and PowerReviews (see Limitations below).

Limitations, Constraints

With Release 17.0, job schedules are optional. The JavaScript controllers 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 your PowerReviews representative for guidance on when these might be needed.

Job schedule for order feed should be configured appropriately. The recommended schedule can be found in the User Guide section of this page, specifically Business Manager. If the job is not configured correctly, order data will not be processed by PowerReviews.

Compatibility

Built on Commerce Cloud 19.6 (Compatibility Mode 18.10) SiteGenesis 104.0.0

Privacy, Payment

There are currently no privacy or payment issues.

Implementation Guide

Setup

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

  • Installation of the cartridge.
  • Import of custom metadata.
  • Setting the newly created metadata values (Site Preference).
  • Importing or creating Product and Order feed job(s).
  • Making storefront cartridge edits.

Cartridge Name

  • int_powerreviews

Scripts

  • impex/libPRExport.js
  • impex/libPRImport.js
  • jobs/import.js
  • jobs/orderFeed.jsa
  • jobs/porductFeed.js
  • jobs/unzip.js
  • jobcontrol/process.js
  • lib/libPowerReviews.js

Static

  • css/reviews_2.css
  • img/interfact/starratings/[rating images]
  • js/powerreviews.js

Templates

  • answers/answers.isml
  • Answers/answersnippet.isml
  • Category//categorysnippet.isml
  • global/global.isml
  • global/definitions/isml
  • order/analyticbeacon.isml
  • pages/writereviewspage.isml
  • pages/pdp.isml
  • rating/reviewstarratings.isml
  • review/reviews.isml
  • review/reviewsnipper.isml
  • review/reviewsrender.isml
  • utils/tabs.isml
  • premail.isml

Resources

  • powerreviews.properties

Properties

  • int_powerreviews.properties

MetaData

  • system-objecttype-extensions.xml

Configuration

  1. Import the int_powerreviews cartridge into the Commerce Cloud Studio Workspace.

    1. Open Commerce Cloud Studio.
    2. Select File > Import > General > Existing Projects Into Workspace.
    3. Browse to the int_powerreviews 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. Select Administration > Sites > Manage Sites > SiteGenesis or needed site.
    3. Select the Settings tab.
    4. Add int_powerreviews to the end of what is already present in the Cartridges field.
    5. Click Apply.
    6. Perform the same steps for Business Manager Site.

  1. Extend the Site Preferences and Product object.

    1. Select Administration >Site DevelopmentImport/Export.
    2. Browse to and select the metadata/metadata_controllers/meta/system-objecttype-extensions.xml file.
    3. Click Upload.
    4. Click the <<Back button.
    5. Click Import.
    6. Select the system-objecttype-extensions.xml file.
    7. Click Next.
    8. When Validation is complete, click Next.
  2. Configure PowerReviews Custom SitePreferences using Commerce Cloud Business Manager.

    1. Select Site Preferences > Custom Preferences > PowerReviews.
    2. Enter the appropriate values (see the Business Manager section for a description of each setting).
    3. Click Apply.
  3. (Optional) Configure Jobs, which are described in the Business Manager section of this page.
  4. 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.

Before Installation: Integration PowerReviews Functionality

Edit storefront templates: [storefront cartridge]/cartridge/templates/default

  1. Open the footer_ui.isml template. Place the following code into the opened template on line 27, below app.js:

    <script src="${URLUtils.staticURL('/js/powerreviews.js')}"></script>

    Example:

    <script src="${URLUtils.staticURL('/js/app.js')}></script>
    <script src="${URLUtils.staticURL('/js/powerreviews.js')]"></script>
    <isif condition="${!('pageContext' in this) || empty(pageContext)}">
    
  1. Open the htmlhead_UI.isml template, and place the following code in the head tag:

    <isinclude template="global/global"/>

    Example:

    <iscomment>THIRD PARTY STYLESHEETS STYLING</iscomment>
    <link href="${URLUtils.staticURL('/lib/jquery/ui/jquery-ui-min-css')}" type="text/css" rel="stylesheet" />
    <link href="//maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css" rel="stylesheet">
    
    <isinclude template="global/global"/>
    
    <!--[if lt IE 9]>
    <script src="${URLUtils.staticURL('/js/lib/html5.js')}"></script>
    <![endif]-->
  1. Open producttopcontent.isml and find the following code snippet:

    <div class="tab"
        <input type="radio" name="css-tabs" id="tab-5" class="tab-switch">
        <label for="tab-5" class="tab-label">$Resource.msg('product.tab.reviews', 'product', null)}</label>
        <div class="tab-content"<isinclude template="product/components/reviews"/>'</div>
        </div>

    replace the second line of code in the snippet above with the following, and delete it:

    <isinclude template="util/tabs"/>
  1. Open the productcontent.isml template and find the following code snippet:

    <iscomment>
        reviews
        =====================================================================================================
        /iscomment
    
        <isif condition="${!isQuickView}">
            <isinclude template="product/components/reviewsmini"/>
        </isif>\

    Next, find the following code:

       </div><!-- end details block -->
        <isif condition="${pdict.GetImages}">
            <div id="update-images" style="display:none">
                <isinclude template="product/components/productimages"/>
            </div>
        </isif>
    </isif>

    Insert the following between the final two </isif> tags:

    <isinclude template="pages/pdp"/>
  1. Open the producttile.isml template and find the following code:

    <isinclude template="product/components/reviewsmini"/>

    Replace it with:

    <isinclude template="rating/reviewsstarratings"/>

    This include can be placed in any tile or recommendation, so long as the template includes a valid page-scoped "Product" variable.

  1. Open app_storefront_core/cartridge/js/pages/search.js and find the following method:

    */
    function updateProductListing(url) {
        if (!url || url === window.location.hreg) {
            return;
        }
        progress.show($('.search-result-content'));
        $('#main').load(util.appendParamToURL(url, 'format', 'ajax'), function () {
            compareWidget.init();
            productTile.init();
            progress.hide();
            history.pushState(undefined, '', url);
        });
    }

    Add the following code to the ajax response, below history.pushState(undefined, '', url);

            if('powerreviews' in app)
        app.powerreviews.render();
    }

    Example:

    progress.show($('.search-result-content'));
    $('main').load(util.appendParamToURL(url, 'format', 'ajax'), function () {
        compareWidget.init();
        productTile.init();
        progress.hide();
        history.pushState(undefined, '', url);
    
        if('powerreviews' in app)
           app.powerreviews.render();
        }
    });
  1. Open productdetail.isml. Above the final </div> statement, insert the following:

    <div.id="pr-reviewdisplay"></div>
    div.id="pr-questiondisplay"></div>
  1. Open producttopcontent.isml and insert the following code on the third line:

    <isinclude template="global/definitions"/>

    Example:

    <iscontent type="text/html" charset="UTF-8" compact="true"/>
    <iscomment>In the product pipeline, if a product was not found for the selected attributes...</iscomment>
    <isinclude template="global/definitions"/>

    The Review and Q&A snippets can be placed anywhere on a PDP page (producttopcontent.isml). However, it is not recommended to place them inside the <div id="product-content'> element, as the content inside that element is reloaded via AJAX when a product's variation is changed. It is recommended to place the snippets inside <div class="product-col-2 product-detail">, right below a product's name.

    Example:

    <div class="product-col-2 product-detail">
        <h1 class="product-name" itemprop="name"></ispring value="${pdict.Product.name}"/><h/1>
    
            <isinclude template="review/reviewsnippet"/>
            <isinclude template="answers/answersnippet"/>
    
        <div id="product content">

Analytic Beacon

Open the confirmation.isml template and find the following code:

<div class"order-confirmation-details">
    <isorderdetails order="${pdict.Order}/>
</div>

Add the following code directly after the preview snippet:

<isinclude template="order/analyticbeacon"/>

Seller Rating Widget

Find the confirmation.isml template and find the following code:

<div class="order-confirmation-details">
     <isorderdetails order="${pdict.Order}"/>
</div>

Add the following code before isorderdertails tag:

<isinclude template="pages/rateshoppingexperience"/>

Example:

<div class="order-confirmation-details">
    <isinclude template="pages/rateshoppingexperience"/>
    <isorderdetails order="${pdict.Order}"/>
</div>

Search Engine Optimization (SEO)

Find the productdetail.isml template and find the following code:

<isobject object="${pdict.Product}" view="detail">
    <div id="pdpMain" class="pdp-main" itemscope itemtype="http://schema.org/Product">
         <iscomment>Image and variation options are part of the include template</iscomment>

Note to the System Integrator

This document uses the convention of app_storefront_controllers and app_storefront_core to refer to the storefront cartridges. You must change those references to names appropriate to your integration target.fer to the storefront cartridges. You must change to those references to names appropriate to your integration target.

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

  • When selecting "read review" on the PDP for 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 get the PowerReviews-provided SFTP credentials for your specific account. The SFTP credentials are used when setting up the Site Preferences.

Testing

Reviews

  • Write Review - Go to the 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 the 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.

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 locale 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 to do.

Business Manager

Site Preferences Configuration

Configuration is stored in the Custom Site Preferences. You can 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.

  • PowerReviews Online Status: toggle on/off PowerReviews integration.
  • API Key: You will receive your API key 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:

    1. From the left navigation select BM > Catalogs > Product and Catalogs.
    2. In the ID column for the catalog that has been assigned to this specific site, look for the string value.

      For example: storerfront-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 multipe 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 businses name. If you have multiple Sites, please append an aunderscore and the Site Name to the file name. Example: "productFeed_MySite_SiteGenesis".
  • PowerReviews Locale Configs: 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.
  • PowerReviews Customer Hash Code: This is a setting that you will receive from PowerReviews.
  • PowerReviews Job Error Email: The email address that you would like to receive potential job error emails at.
  • PowerReviews Job From Email: The email address that you would like to receive from potential Job error emails at.
  • PowerReviews Show Variants: A controller to allow toggle on/off output of product variation ID on Write Review, Question and Answer pages.
  • PR Stylesheet Override: If you would like to use your own styles for the Reviews and Q&A display, then include the full URL of the stylesheet here.
  • PowerReviews FTP Password: This is a setting that you will receive from PowerReviews.
  • PowerReviews FTP Host: This is a setting that you will receive from PowerReviews.
  • PowerReviews FTP Username: This is a setting that you will receive from PowerReviews.
  • PowerReviews Trigger File Action: Value YES - trigger file will be removed and new zip will be downloaded from FTP server. Value NO - trigger file will be removed and a new zip file will be downloaded from the FTP server.
  • PowerReviews Trigger File Name: This should always be "done_MGID.txt" unless you are using the PowerReviews testing files, in which case you'll use "done_MGID_test.txt".
  • PowerReviews Zip File Name: This should always be ""MGID.zip" unless you are using the PowerReviews testing files, in which case you'll use "MGID_test.zip".
  • PowerReviews Master Merchant: This option should only be checked if specified by PowerRevews when you receive your account details. If you are unsure about whether or not to check this, contact PowerReviews.
  • SFTP Port Number: This a setting you will receive from PowerReviews.
  • Controllers Mode: Check this preference if your site is based on controllers model.
  • 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 the Seller Rating widget only.
  • PowerReviews Seller Rating API Key: This is a setting you will receive from PowerReviews. This configuration is used for the Seller Rating widget only.
  • PowerReviews Seller Rating Merchant GroupId: This is a setting that you will receive from PowerReviews. This configuration is used for the Seller Rating widget only.
  • PowerReviews Seller Rating Merchant PageId: This is a setting that you will receive from PowerReviews. This configuration is used for the Seller Rating Widget only.

Site Locale Configuration

Each locale can be configured with the appropriate pattern:

[DW_Locale]|[PowerReviews_Merchant_Id]

Example:

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:

  1. Select Business ManagerAdministration > Operations > Job Schedules > New.
  2. Create the following Jobs:

    PowerReviewsFullProcess

    1. For Name use PowerReviewsFullProcess.
    2. For Enabled use  true.
    3. For Description use 'This job runs the full PowerReviews update process, which includes: exporting orders and exporting products for pickup by PowerReviews'.
    4. For Execution Scope use Sites.
    5. For Controlleruse IntPowerReviews.
    6. For Startnodeuse FullProcess.
    7. Schedule: Schedule this job to run as necessary.
    8. Click the Sites tab and check the checkbox of each site for which you want to run PowerReviews.
    9. Click Apply.

    The PowerReviewsFullProcess job essentially runs the PowerReviewsProductFeed and PowerReviewsOrderFeed jobs, detailed below.

    This job should be setup in the Staging environment. Having this setup in Staging means that you'll be able to test and see rendered reviews and all of the functionality in a non-live environment. When you replicate Staging to Production, the imported PowerReviews data will also be replicated.

  3. PowerReviewsProductFeed

    1. For Name use PowerReviewsProductFeed.
    2. For Enabled use  true.
    3. For Execution Scope use Sites.
    4. For Controller use IntPowerReviews.
    5. For Startnode use ProductFeed.
    6. For 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.
    7. Click the Sites tab and check the checkbox of each Site for which you'd like to run PowerReviews.
    8. Click Apply.

    This job should set up in the Production environment. The Order Feed data is environment-dependent. For example, if you run this job from Production, the product URLs that are eported will be Production product URLs.

    PwerReviewsOrderFeed

    1. For Name use PowerReviewsOrderFeed.
    2. For Enabled use true.
    3. For Execution Scope use Sites.
    4. For Controller use IntPowerReviews.
    5. For Startnode use OrderFeed.
    6. For Schedule, the initial run should be run manually for initialization inner timer.

      Further execution of this job should be configured in the appropriate way. Recommended scheduling of this job is twice a week.

    7. Click the Sites tab and check the checkbox of each Site you'd like to run PowerReviews for.
    8. Click Apply.

    This job should be setup in the Production environment. The Order 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.

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.
18.3.0 5/3/2018 Moved all PowerReviews render() calls out of the templates and into one external JavaScript object that is fired once after the DOM completes. Added an app.powerreviews object that can be called from anywhere, including recommendations and category or PDP update methods.
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!