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 |
|
Reference Architecture Details |
|
Development and Build Process |
|
Site Configurations |
|
Legacy Data Migration |
|
Architecture and Data Flows |
|
Integrations |
|
Key Customizations |
|
Security |
|
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.
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 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:
|
Multi-region brand site(s):
|
Single Region |
Multi-brand regional site(s):
|
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: brand-a.domain.com |
Multi-region brand site(s): www.brand-a.com |
Single Region |
Multi-brand regional site(s): eur.domain.com brand-a.fr |
Dedicated sites (for each brand and region): www.brand-a.com |
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: |
Multi-region brand site(s):
|
Single Region |
Multi-brand regional site(s):
|
Dedicated sites (for each brand and region):
|
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:
|
Multi-region brand site(s):
|
Single Region |
Multi-brand regional site(s):
|
Dedicated sites (for each brand and region):
|
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