Create the Technical Specification

Learning Objectives

After completing this unit, you’ll be able to:

• List the general contents of a technical specification.
• Describe the reference architecture details that you need to document.
• List the reference architecture features that you should describe in the technical specification.
• List the basic steps of the Salesforce B2C Commerce storefront build process.
• Describe three site model strategies.

Capture the Details

As you learned in the last unit, the technical specification is one of the key documents that you as the technical architect must deliver. Your attention to detail in this document can propel your project a long way on the road to a successful implementation. Here’s what’s typically in this document.

The Overview

Start by documenting resource locations, including reference documentation and data samples. The sample XML data files you use must validate against the B2C Commerce import and export schemas.

A system of record table is essential for maintenance planning. A system of record is the authoritative data source for a specific type of information. For example, catalog data is often created in a system of record, and then imported into B2C Commerce for storefront usage. Here’s what a typical system of record table looks like.

The Reference Architecture

The next section in the technical specification documents the storefront reference architecture you plan to use. For example, for the Storefront Reference Architecture (SFRA), document storefront features like these.

• Global header and footer
• Homepage
• Category landing page
• Search results page with product grid
• Refinements on category landing pages or search results page
• Product details pages

See the Salesforce B2C Commerce Launch Readiness module, the “Compare Business Requirements with the Storefront” unit, for details.

Naming Conventions

File naming conventions make code more understandable and provide key details about the function of the identifier. Here are some important conventions.

Review best practices in the Salesforce B2C Commerce Functional Consulting Strategy module. Document them in the technical specification.

The Build Process

Document the merchant’s build process, including the name and location of the build server. An automated build process should look something like this.

1. Download the code from the GitHub repository.
2. Run the build process from the B2C Commerce Jenkins server to:
   • Create the cartridge and upload it to the staging server (with multi-factor authentication enabled).
   • Activate the version of the uploaded code.
   • Send emails about the new build.

Cartridges

A cartridge is a container for packaging and deploying program code and data. Create a table like this to document the cartridges.

The Site Model

At the planning stage, identify the best site model strategy from several approaches. Here are some choices.

• One site: a unique site for all targeted countries or brands
• Group of sites: several sites to address all targeted countries or brands
  • Group select countries together based on shared currencies, legal requirements, or language.
  • Group brands based on the ability to combine the products in a shared cart and their similarities in styling and user flows.
• One site for each: multiple dedicated sites per targeted country or brand

The best practice approach depends on the merchant’s context and constraints. Each site model uses certain platform features differently, as shown here. 

Site Aliases and URLs

For site aliases and URLs, combined and multi-brand regional sites can use session redirects between brand-specific site aliases to implement a shared cart. Here’s what the URLs look like.

Shared Sessions for a Site with Multiple Domain Aliases

Consider a merchant with multiple brands. The merchant gives each brand its own host name, but keeps all brands on the same site. The merchant’s goal is that a shopper uses a single basket and retains session information when they switch between brands via a redirect link. This means that:

• Shoppers can shop several brands with one checkout.
• Authenticated shoppers don’t have to log in again when switching brands.
• You can create cross-brand campaigns and promotions for qualifying products in the basket.

Don't hardcode URLs. Use this API method to provide links between brands on storefront pages: URL dw.web.URLUtils.sessionRedirect(String host, URL url)

This method generates redirect URLs to the target host name, and preserves the current storefront session. It doesn't work with direct storefront links. If the shopper changes the URL instead of clicking the redirect link, the session isn’t preserved. This works within one site; you can’t share sessions and baskets across sites.

Promotions and the Region Selector

When the same product is offered in multiple regions in multiple currencies, some shoppers shop for a better price. If the merchant doesn’t want to allow that, here’s what you can propose.

• Use location-based redirects/site selection to limit this behavior (except in Europe, as noted).
• Apply high cross-border delivery costs, or don’t offer cross-border delivery to certain regions.

Here are your promotion choices.

European geo-blocking (automated redirects) requires explicit shopper consent, unless there are additional regulations by the client/trader in certain EU countries.

Content

Multi-brand sites with brands that have the same look and feel can share content. A shared library reduces maintenance costs, while a private content library provides more flexibility.

Customer Groups

Create dynamic customer groups to reduce architectural complexity for brand- and locale-specific experiences. For example, create a brand-specific customer group with a Session custom attribute qualifier based on request.httpHost.

Next Steps

In this unit, you got an overview of the technical specification and focused on the reference architecture and build process sections. You also learned about site model strategies. Next, learn how to map the merchant’s data.

Resources

• Salesforce Help: B2C Commerce import and export schemas
• Salesforce Help: SFRA
• Trailhead: Salesforce B2C Commerce Launch Readiness
• Trailhead: Salesforce B2C Commerce Functional Consulting Strategy
• Trailhead: Salesforce B2C Commerce Cartridges
• External link: Official Journal of the European Union: REGULATION (EU) 2018/302