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.

Topic	Contents
Overview	Document references File location of storefront architecture sample data to provide validation System of records location and change frequency Disclaimers Open items Glossary of terms
Reference Architecture Details	Functionality description Responsive design requirements per device type Gap analysis Best practices Coding standards Naming conventions Development best practices
Development and Build Process	Development Build process
Site Configurations	Sites Catalog Cartridge Price book Inventory Shipping Customer list Order Service framework Content Redirect SEO WebDAV and SFTP Data retention API quota
Legacy Data Migration	Customer Order Promotion Payment instrument
Architecture and Data Flows	Architectural considerations Data mapping Custom attributes Data feeds and replication schedule
Integrations	Third-party integrations Infrastructure service delivery (ISD)
Key Customizations	Backend customization Front-end customization Business Manager customization
Security	User and shopper security Storefront data protection Monitoring and support Secure code and features
Testing	User acceptance Performance testing Load testing

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.

Data Type	Location	System of Record	Change Frequency
Products
Categories
Promotions
Images
Inventory
Order
Price Book
Customers
Content

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.

Type	Description	Owner
Classes, namespaces	All identifiers are in mixed case with a capital first letter. Don’t start class names with underscore _ or dollar sign $ characters, even though they are allowed.	NavigationHelper
Functions	All identifiers are in mixed case with a lowercase first letter. Internal words start with uppercase letters. Don’t start variable names with underscore _ or dollar sign $ characters, even though they are allowed.	getBackground();
Variables	Use the variable name followed by a colon and the type definition. The colon is between spaces.	var myName : String; var myWidth : Number;

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.

Download the code from the GitHub repository.
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.

Development, integration, and testing should occur on sandboxes or the development instances, and not on staging. The merchant's admin replicates the code from staging to development. This is recommended due to the 2FA requirement for code upload. They should also import the site configuration manually on staging and replicate it to development on a daily basis. This ensures that there’s a complete code and data build on staging and development. They can deploy code without activation on staging.

Cartridges

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

Cartridge Name	LINK Cartridge Version	Comment

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 site model can be one site, a group of sites, or multiple dedicated sites for each target 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 Scope

Multiple Brands

Single Brand

Multiple Regions

Combined site:

Multiple currencies
Shared cart

Multi-region brand site(s):

Multiple currencies

Single Region

Multi-brand regional site(s):

Shared cart

Dedicated sites (for each brand and region)

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.

Site Scope

Multiple Brands

Single Brand

Multiple Regions

Combined site:
www.domain.com

brand-a.domain.com
brand-b.domain.com

Multi-region brand site(s):

www.brand-a.com
www.brand-b.com

Single Region

Multi-brand regional site(s):

eur.domain.com
usd.domain.com

brand-a.fr
brand-a.co.uk

Dedicated sites (for each brand and region):

www.brand-a.com
www.brand-b.fr
www.brand-b.co.uk

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.

Site Scope

Multiple Brands

Single Brand

Multiple Regions

Combined site:
Use all choices listed in this table

Multi-region brand site(s):

Percent-off preferred
Currency specific amount-off

Single Region

Multi-brand regional site(s):

Product/category level preferred
Order level promotions are tricky because of currency and tax

Dedicated sites (for each brand and region):

Use all promotions without limits

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.

Site Scope

Multiple Brands

Single Brand

Multiple Regions

Combined site:

Only shared library
Brand-specific content possible with naming convention

Multi-region brand site(s):

Can use either

Single Region

Multi-brand regional site(s):

Brand-specific content possible with naming convention when sharing

Dedicated sites (for each brand and region):

Can use either

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.

Create the Technical Specification

Learning Objectives

Capture the Details

The Overview

The Reference Architecture

The Build Process

The Site Model

Next Steps

Resources