The Salesforce B2C Commerce is a unified commerce solution that provides core commerce

functionality, product management, order management, and customer experience management. It

connects customers, through a variety of touch points to an integrated shopping experience, whether it

originated online or in-store.

Order processing and fulfillment are handled by Commerce Cloud Order Management or another

integrated order management system. Predictive intelligence and personalization are provided by the

Commerce Cloud Einstein engine or an integrated system. Third-party integrations can be configured to

provide additional services such as ratings and recommendations, payment services, and email

marketing.

, the architecture of B2C Commerce is distributed through numerous data centers

on several continents. Each data center hosts a combination of hardware and software that we refer to
as a point of delivery (POD).

PODs are divided into two or more realms, through which retailers’ storefronts connect to B2C

Commerce. Realms contain instances. An instance is a copy of a client's sites, configurations, and

customizations. Instances in a realm are separated into two instance groups:

The Primary Instance Group (PIG) contains these instances:

• The Staging instance is an environment where system administrators import data and upload code

to prepare it for testing. Merchants create and maintain storefront data in the staging instance.

• The Development instance simulates the production environment and is where testers evaluate

features and processes before they are deployed from staging to production.

• The Production instance is a live storefront.

The Secondary Instance Group (SIG) contains B2C Commerce sandboxes in which developers create and

test code. Sandboxes are not as powerful as PIG instances in terms of performance, memory, and

storage.

The demo instance is a dedicated sandbox that is reinitialized with each release so that it always has the

latest version of SiteGenesis for reference. Because the demo instance is frequently overwritten with
new releases, it is not intended to store data or active development work.

Every B2C Commerce instance has its own Business Manager.

Although the Business Manager is used most frequently by merchants to manage storefront data, it is
also used by developers. Developers use the Business Manager to deploy code, define system and

custom objects, add cartridges to a site, and adjust Open Commerce API (OCAPI) settings. They also

manage site development, code versions, data import and export, page caching, site indexing, and

global preferences for all of the sites in a single instance.

Commerce Cloud has two reference architectures: SiteGenesis and the new Storefront Reference

Architecture.

Most developers are familiar with Commerce Cloud's best-in-class SiteGenesis architecture, which is

currently used by over 2,700 Commerce Cloud sites. SiteGeensis and is a proven foundation for some of

the world's leading brands. The future of SiteGenesis is strong, it will continue to be supported and

receive maintenance and as always, SiteGenesis customers will continue to receive platform innovation

through the Commerce Cloud API layer. There is no plan to discontinue support.

Based on the best-in-class SiteGenesis framework, Storefront Reference Architecture, combines best

practices in mobile site design and technical storefront architecture, to provide a blueprint for
merchants looking to build and customize their ecommerce storefronts.

Storefront reference architecture leverages:

• The JavaScript controllers development model along with a new storefront architecture and

customization model intended to make it easier for development teams to follow a model-view-

controller (MVC) approach.

• User Experience (UX) best practices, data driven design, and the popular Bootstrap mobile UI

framework to optimize the shopping experience across mobile devices, while delivering a great

desktop site experience as well.

The SiteGenesis ecommerce site is a customizable reference application that developers and merchants

use to explore B2C Commerce and learn about its features and capabilities. For developers, it provides

sample code in the form of JavaScript controllers, pipelines, scripts, and templates. For merchants, it

provides sample storefront data, including: catalogs, categories, products, price books, promotions,

content assets and slots, locales, and currencies.

Importing SiteGenesis

Because it is a full-featured sample storefront site, developers can use SiteGenesis as the foundation for

new sites. Import the current version of the SiteGenesis package (read-only) as a sample site where it is
convenient / into every sandbox instance. To avoid overwriting custom attributes and data, import

SiteGenesis into an empty sandbox before importing custom sites. After you import SiteGenesis, validate
its behavior by comparing it to the site in the demo instance.

Import the latest version of SiteGenesis

1. Log into the Business Manager.

2. Select Administration > Site Development > Site Import & Export.

3. Select to import from a local instance.

Import a site from a local copy

1. Select the SiteGenesis Demo Site. (Alternatively, click Browse to select another file and then click

Upload to make the file local).

A confirmation message is displayed.

2. Click OK.

You can view the status of the import in the Status section of the page. When the import has

completed, Business Manager lists the new site. You will also receive an email that the job has

completed.

When your import has completed, Business Manager lists the new site. You will also receive an email
that the job is complete.

After you create an empty site, there are two configuration tasks to complete:

1. If you want to see code changes immediately, you must disable site caching in your sandbox. By

disabling the page cache, you can see the most recent code changes reflected in your site. Site

caching is on by default in production instances.

2. Before you can search for products on the storefront, you must index the storefront site.

A workspace is an Eclipse-specific local directory that contains Eclipse projects. Standard Eclipse projects

are usually connected to Java source directories (packages). UX Studio projects, however, either define a

connection to a B2C Commerce instance, or point to a B2C Commerce cartridge. UX Studio projects

never compile Java projects because Java code is not used in B2C Commerce programming.

You must create a server connection in UX Studio to be able to upload your code to the B2C Commerce

server instance. Note: It is a one-way push connection; you cannot pull code onto a local computer from

the B2C Commerce server.

Studio. This enables you to push your code to the server instance. However, you will not be able to pull

the code onto your local computer from the B2C Commerce server—as it is a one-way push connection.

Note: Connections to staging instances require two-factor authentication.

The UX Studio plugin provides access to lists B2C Commerce programming files, which are sorted and

displayed in their own views.

A cartridge is a folder containing a set of resources that provide specific storefront features or an
external

integration. Every cartridge is fully contained within one folder. Each cartridge folder has specific

subfolders for different types of resources, including pipelines, templates, scripts, forms, and static

content, such as image files, CSS files, and client-side JavaScript files. Each type of resource must be

stored in its corresponding folder. You introduce new functionality to a storefront by adding new

cartridges.

After you add a cartridge to your storefront, use the Business Manager to update the cartridge path so

that the storefront recognizes the new cartridge. The cartridge path is a colon-separated, ordered list of

cartridges that defines code execution precedence.

When the storefront executes code, it follows the cartridge path. Cartridges at the beginning of the

cartridge path take precedence over cartridges at the end of the cartridge path. For example, suppose

that your storefront code calls product.isml. If storefront_cartridgeB and storefront_cartridgeC both

contain a product.isml file, then B2C Commerce uses the first one it finds, the product.isml file in

storefront_cartridgeB.

Every new site has at least one cartridge. You can introduce new functionality to a storefront by adding

new cartridges as needed to satisfy your business requirements.

When you need to segregate code between sites, you may want to create a new empty cartridge. This

enables you to add only the code you need for a site (or specific sites) in an organization.

When you create a new storefront cartridge in UX Studio, a copy of the SiteGenesis cartridge downloads

to your workspace and is renamed with the name you specify. The reference cartridge has all of the
code

needed for a SiteGenesis storefront to work in B2C Commerce. It contains:

• The simple presentation layer, including ISML templates, common CSS files, forms, and resource files.

• The specific CSS required create the look and feel of the SiteGenesis storefront.

Changes made to the new storefront cartridge are uploaded to the server. To view them immediately:

1. Set the cartridge to be uploaded to your server.

2. Put the new cartridge in the cartridge path.

3. Disable site caching for the site.

Since pipelines are the legacy controller in B2C Commerce, the “new” module would logically be

controllers. There are two types of controllers: Pipeline and JavaScript.

Pipelines are stored in XML files in the file system, both locally and on the server. You define and store

pipelines within the context of a cartridge.

When the storefront application references a pipeline in a cartridge, it searches for the controller with

that name first. If the controller is not found, then it searches for a pipeline with that name. When a

pipeline and a controller with the same name exists on two cartridges, the controller will run no matter

where it shows up in the path. If there are multiple controllers, the first one found will run. If there is no

controller but pipelines, the first pipeline will run. Therefore, use unique pipeline and controller names
to ensure that the framework locates the correct pipeline or controller.

Use the require keyword to load a class or package from the API, or scripts from cartridges into the

code. The return value is an instance of the loaded module, which can optionally be stored in a variable.

The guard exposes the function. In this case, the start function is exposed to the URL with the name

Start. It can also enforce an http method. In this example, it is exposing the function with a get

method.

The ISML object gives control to the ISML template, which displays the results. Pass results to the ISML

template to render the output. (ISML serves as the view, much like JSP or ASP.) This example outputs
the

results to an ISML template named demo.isml, and passes a string message called myParameter.

Note: You can use a response object directly to display the results as shown but it is not recommended.

The myParameter parameter is loaded on a hashmap named pdict and can be retrieved from

demo.isml using the syntax: ${pdict.myParameter}

performance.

Earlier versions of SiteGenesis used importPackage to import B2C Commerce packages into scripts.

Require is now the recommended approach because it is flexible, uses CommonJS syntax, and improves

performance. You may still see importPackage if you are maintaining a site based on an earlier version

of SiteGenesis.

Every CommonJS module object has an exports property which can be used by the module

implementation to expose its public functions or properties. Only functions and properties that are

explicitly exported are accessible from other modules, all others are private and not visible.

For controllers, SiteGenesis uses the concept of guards to wrap controller functions when they are

exported. The functions in the guard module act as a request filter and let you specify multiple levels of

access to controller functionality, such as:

• require HTTPS

• require or forbid a certain HTTP method, like GET, POST,...

• require that the current customer is logged in

• require that the function may only be executed as remote include, but not as top-level request

A guard is a wrapper function that encapsulates a delegate function and only invokes it if

its guard condition is satisfied. The guard conditions represent single preconditions that can also be

combined with each other. The conditions use the B2C Commerce API to determine the properties of

the current request and logic to determine whether to continue request processing or throw an error.

Example: require GET

exports.StartCheckout = guard.ensure(['get'], startCheckout);

Example: require HTTPS and that the customer is logged in.

exports.EditProfile = guard.ensure(['get', 'https', 'loggedIn'],

editProfile);

Note: You can also create custom guards functions, such as "stagingOnly" or "loggedInAsEmployee".

The Request Log tool enables you to troubleshoot error messages on your storefront.

It displays the log for the last request and any request prior to that request during the current session.

You can view both debug messages and error messages.

Internet Store Markup Language (ISML) is a Salesforce-proprietary, ecommerce-related HTML extension.

ISML templates are files that contain ISML tags and expressions, and have an .isml extension.

ISML templates define how data, tags, and page markup are transformed into dynamic HTML responses.

The templates apply CSS to format the HTML responses sent back to users’ web browsers.

As you learned in Salesforce B2C Commerce Architecture Overview, within the Model View Controller

(MVC) architectural pattern:

The model is represented by the B2C Commerce Script API.

The view is represented by ISML templates.

The controller is represented by pipelines or JavaScript controllers.

To create an ISML template:

1. In UX Studio, select a cartridge in Navigator View. Select File > New > ISML Template. The Create

Template dialog displays.

2. In the parent folder field, enter the name of the folder where you want to store your template. If the

folder does not exist, it will be created.

3. In the Template name box, enter a name for your template. You do not need to enter the .isml

extension.

4. Click Finish.

Your new template opens in the ISML editor in UX Studio. This editor supports HTML and ISML system

tag auto-completions as shown.

ISML tags:

• Are Salesforce-proprietary HTML extensions that developers use inside ISML templates

• Start with is (for example <isprint>)

• Combine with HTML to define how dynamic data is presented on the page that is returned to the

user’s browser

• Both ISML tags and expressions are used only in ISML templates

A content slot is an area on the storefront page where a merchant defines content to display based on

certain qualifiers or rules. Content slots display:

• Category attributes (such as images)

• Content assets (from the content library)

• Static HTML and images (from the static library)

• Recommendations generated by predictive intelligence

To identify a content slot on the storefront, select Content Information in the Storefront Toolkit. Then

move your mouse pointer around the page to reveal content slots. For each content slot, a popup box

includes a link to the slot configuration in the Business Manager.

Content slots and content assets are managed in different areas within the Business Manager.

To configure slots in the Business Manager, navigate to Merchant Tools > Online Marketing > Content

Slots.

To manage content assets in the Business Manager, navigate to Merchant Tools > Content > Content

Assets.

Creating a content slot typically requires collaboration between a developer and a merchant.

First, the developer adds a content slot to a template, positioning the <isslot> tag exactly where the

slot should be displayed on the page. Then the developer creates a slot rendering template that defines

how the slot content should be presented. Finally, the merchant creates a slot configuration, defining

what is displayed within the slot. Merchants configure slots to change content regularly and keep the

storefront fresh for returning visitors.

Many factors influence what is displayed in a content slot: campaigns, ranks, A/B tests, schedules, and

customer groups. (Campaigns and A/B tests are beyond the scope of this course.)

Merchants create content slot configurations by navigating to Merchant Tools > Online Marketing >

Content Slots and locating the specific slot that the developer created, for example, header-banner.

The merchant can edit an existing configuration or click New to create a new one.

The merchant selects a content type, which determines which additional fields are displayed. For

example:

• When the content type is Product, the merchant enters the IDs of the products to be displayed.

Then the merchant selects from the Template list a template designed to display products.
• When the content type is HTML, the merchant enters the HTML content to be displayed. Then the

merchant selects from the Template list a template designed to display HTML.

The Template list displays rendering templates of the selected content type.

This list includes all templates in all of the cartridges in the cartridge path.

The merchant can choose to reuse an existing rendering template or create a

new one as instructed by the developer. This is why the collaboration

between merchant and developer is important. If they don’t coordinate the

slot, the rendering template, and the slot configuration, the slot is not

displayed correctly on the storefront.

The SiteGenesis storefront cartridge includes default rendering templates for

each content type, stored in content type folders within the slots folder.

The merchant also selects a schedule for the slot configuration:

• Default enables adding a schedule that is not from a campaign or A/B test to

the slot configuration.

• Campaign enables use of a schedule that is defined within a marketing

campaign (when a campaign is configured for the slot).

• A/B Test enables use of a schedule that is defined within an A/B test (when

an A/B test is configured for the slot).

The B2C Commerce forms framework provides tools to simplify form display and processing. Use the

forms framework to control how consumer-entered values are validated by the application, rendered in
a

browser, and optionally stored on a server.

To use the forms framework, you need the following files:

• An xml form to define and store the metadata

• A controller to validate and process the form (not shown in the diagram)

• A properties file to externalize form labels and error messages (not shown in the diagram)

• An ISML template to display the form

There are three objects that interact when working with B2C Commerce forms:

• XML metadata file: located in the cartridge/forms/default directory. It describes the fields,
labels, validation rules and actions that apply when the field is used in an ISML template.

• ISML template: it uses the form metadata fields and actions to show an HTML form to the user.

• Object (optional): this object represents a single system or custom object in the controller, and it

can be used to pre-fill the metadata file as well as to store submitted form data to the database.

In an ISML template, create a form whose fields are defined by the values in the form metadata.

To prefill the form with data from the database, bind an object that contains the data to the form

metadata file. The prefilled data appears in the ISML template because the template references the
form

fields, which are bound to the object.

The form metadata file defines the fields displayed on the form and the actions that can be performed

on the form. This information typically comes from a wireframe or a functional specification. Once the

form fields are determined, create them in an xml form that will set the form field parameters and hold

the data for the form.

In this example, the fname, lname and email fields store the information needed to send a newsletter

to a non-registered user. These fields are mandatory, and each field has a label key that points to the

cartridge/templates/resources/forms.properties file.

In addition, the email field uses a regular expression (regexp) to define an acceptable email address.

The regular expression specifies a parse-error key that matches an error message in the

forms.properties file.

The subscribe action enables a user to submit the form. valid-form="true" requires the form to be

validated. Server-side validation ensures that this form contains three required field values and a valid

email format.

Although it is not required, the SiteGenesis Style Guide recommends using lower-case letters in xml form
names.

Use the Forms Framework, you created a simple form and displayed it. You

validated the data being submitted, but did not store the data permanently. To store data permanently,

use data objects, which are persistent. B2C Commerce supports both system objects (such as catalog,

order, and product) and custom objects, which you define.

Extending an existing system object by adding new attributes is preferable to creating a new custom
object type. Because system objects are optimized for search and retrieval, they provide better site

performance. When you think you need a custom object type, first evaluate all related system objects

and their attributes. If you can’t use or extend a system object to meet your needs, then create a custom
object type.

Custom objects extend the B2C Commerce data model.

A custom object is implemented as a new table in the database. You specify the primary key and storage

characteristics, such as replicability and retention.

Keep in mind that custom objects are intended for small amounts of static data, such as configuration

parameters for external system integrations (eliminating the need for multiple site preferences). They
are

not designed to handle large, uncontrolled volumes of data, such as those generated by analytics.

As the data for a custom object grows, searches take longer to return results. When you create a custom

object, be sure to plan for growth and cleanup.

B2C Commerce Governance enforces quotas around custom object API usage and data size. Attempts to

exceed the quota result in a runtime error.

Created at the organization level, custom object types are accessible to all sites in the organization.

In the Business Manager, use the Custom Object Types module (Administration > Site Development >

Custom Object Types) to create and manage custom object types.

Storage Scope specifies the scope of individual instances of the custom object as either:

• Organization: Custom objects are available to all sites in the organization.

• Site: Custom objects are available to the site that created them and not to other sites in the

organization.

Data Replication specifies whether the custom object instances are replicable (included in the

replication process from Staging to Production or Development).

Retention specifies how long the custom object should be kept. You also need to consider how to clean

up custom objects after they are exported or after a certain expiration period. This means the creation
of

a cleanup batch job that should run on a schedule.

You create custom objects either in the Business Manager or via B2C Commerce Script for the
storefront.
In the Business Manager, use the Custom Object Editor module (Merhant Tools > Custom Objects >

Custom Object Editor) to create and manage custom objects.

An example of a custom object is a newsletter subscription. B2C Commerce does not have a system

object to support the data for newsletter subscriptions. It is tempting to add the subscription data to the

Profile system object, but this would allow only registered users to subscribe. To enable unregistered

users to subscribe to the newsletter, you need a custom object.

Subscriptions are exported because B2C Commerce should not be used for mass mailing campaigns.

Subscriptions are not replicable because they should not be replicated from Staging to Production.

You have created a form to collect information for newsletter subscriptions. You have created a

corresponding custom object to store subscription data collected by the form. Now, you can connect the

form fields to their corresponding custom object attributes by binding them. The benefits of binding a

form and its fields to an object and its attributes are:

• The object is automatically updated with form data. (There is no need to use an insert statement or

call an API.)

• Form fields can be pre-populated with data from the object.

Data binding has two requirements:

• The bound object must be a system object or a custom object, and it must be available in the

controller.

• The form must specify the binding attribute for at least one field.

In this example, the form binds the fname, lname, and email fields to the custom.firstName,

custom.lastName, and custom.email object attributes.

Page download time is a critical factor in keeping visitors on your storefront. The longer it takes to

download a page, the higher your risk of losing a sale.

Rendering pages that contain many business objects, or perform complex calculations, consumes

significant server resources. Therefore, it can help to cache pages that do not differ from one customer
to

another, such as product detail pages, and pages that do not change often, such as search result pages.

Resources wasted by processing static pages for each customer (instead of caching them) slows the

storefront site for all users and all pages. Degraded performance impacts job processes as well.
To minimize page download time, cache appropriate pages as much as possible.

B2C Commerce follows these <iscache> tag rules:

• If the <iscache> tag occurs multiple times in a template or its locally included templates, the shortest

duration is used.

• Caching from a local include affects the including template.

• If there is no <iscache> defined, the template is not cached.

Stored pages are invalidated and new ones are pulled from the application server only when these
events

occur:

• The defined caching time is exceeded.

• A replication has been performed (with the exception of coupons and geolocation data).

• An explicit page cache invalidation is triggered by a merchant in the Business Manager.

As a best practice, disable page caching on sandbox, development, staging instances so that you see

changes immediately. In Production, caching is on by default.

Portions of pages can be cached separately. Use remote includes to assemble a page from snippets with

different caching attributes. Each part:

• Must be a result of a request to the application server.

• Is included using the <isinclude url=""> or the <iscomponent pipeline=….> syntax.

(Remember that all content slots are implemented by <isinclude> tags.)

• Can have its own cache time or no caching at all.

Frequently changing pages benefit from a shorter caching period. Stored pages are only invalidated and
a new

one pulled from the application server if any of the following occur:

• The defined caching time is exceeded.

• A replication has been performed (with the exception of coupons and geolocation data).

• An explicit page cache invalidation is triggered by a merchant in Business Manager.

In general, do not cache pages that show buyer or session information.

To see how partial page caching is implemented for a page, select the Cache Information tool in the

Storefront Toolkit. When the Cache Information tool is selected, icons on storefront pages reveal details
about how the page and its remote includes are cached.

The pipeline profiler is a Business Manager tool that provides operating statistics for pipelines,

controllers, and JavaScript. It tracks execution metrics, which are an indicator of overall page and site

performance. Use the pipeline profiler during site and application development to identify performance

bottlenecks.

To access B2C Commerce caching metrics, select Merchant Tools > Analytics > Technical Reports.

This sample report reveals that the Home-Show controller (which generates the homepage) is not

cached. The Caching column shows red for all hits. If you see this trend in your analytics data, consider

altering the caching settings or the caching interval.

Typically, the most critical performance measure is the average response time. The most important

controllers to monitor are Search-Show and Product-Show, which are the primary components of most

pages on B2C Commerce storefronts.

• Search-Show: If pages generated by the Search-Show controller load in 400ms or less, the storefront

is performing well.

• Product-Show: If pages generated by the Product-Show controller load in 320-400ms, the storefront

is performing well.

Salesforce strongly recommends that you check analytics reports to track these metrics every week and

any time you make code changes.