1. Introduction
FirstSpirit is used for creating versatile and project-specific content. Thanks to the ContentConnect module, it is now possible to transfer this content to the Salesforce Commerce Cloud e-commerce shop system and use it there.
In the remainder of this document, the abbreviated form “Commerce Cloud” will be used instead of “Salesforce Commerce Cloud”. This abbreviated form refers to Salesforce Commerce Cloud in all cases. |
The module combines the functional strengths of both systems, delivering the key advantages that each offers and creating a highly effective overall system made up of two areas that work in parallel and are largely decoupled from one another:
- Components on the FirstSpirit side
-
These components are used for creating and maintaining editorial data, which is transferred to Commerce Cloud in the form of XML files and media.
- Components on the Commerce Cloud side
-
These components are used for processing editorial content created in FirstSpirit. Commerce Cloud integrates this data into the shop and transfers it to the live state.
A part of the delivery of the ContentConnect module is a StarterPackage, including a reference project and various cartridge components, which in large part are set up on the Storefront Reference Architecture. This documentation is consistently based on the reference project and provides an explanation of the functions made available by the module using common use cases. Description is given from the view of an editor as well as a FirstSpirit developer.
1.1. Range of functions
ContentConnect allows editors to:
-
Create native Commerce Cloud content using FirstSpirit
-
Access product information via the
Open Commerce API
(OC API) -
Display shop elements and editorial content in the FirstSpirit preview simultaneously
-
Transfer content to the Commerce Cloud storage location via
WebDAV
The corresponding functions are made available in both the SiteArchitect and the ContentCreator when the module is installed and configured.
Familiar FirstSpirit tools are used to maintain the content, meaning that editors who are already familiar with FirstSpirit do not require any additional knowledge. The content is made available to Commerce Cloud as part of a deployment so that it can be imported. Commerce Cloud then transfers the information to the live state.
As far as Commerce Cloud is concerned, this means there is no difference when it comes to delivering editorial content to the live state. Even if the FirstSpirit server is shut down because of maintenance work, for example, this has no effect on Commerce Cloud.
1.2. Architecture
FirstSpirit and Commerce Cloud are linked by an architecture made up of a range of components (see figure Architecture). These components are:
-
The modules installed on the FirstSpirit server:
-
ContentConnect module
-
WebDAV module
-
JSTL module
-
-
Commerce Cloud instances (Staging & Production)
The individual components always interact in accordance with the following schema:
-
The editorial content is created and edited in FirstSpirit. The content replaces placeholders in the HTML framework; however, the framework - like the products displayed on the live page - comes from Commerce Cloud. It is transferred via
https
to FirstSpirit, where it is required in order to display the preview in full. For product and category pages, this also requires communication with controllers that are part of the delivered cartridge. Products are transferred to FirstSpirit via theOC API
interface of the Commerce Cloud Staging instance. This interface is also used to start various actions in the Commerce Cloud. -
All content changes carried out in FirstSpirit are made available to the Commerce Cloud Staging instance via
WebDAV
as part of a deployment. They are stored in variousWebDAV
directories in the form of media and XML files. From this point, they are then imported into the Commerce Cloud Staging instance library via jobs, which are initiated by a deployment action. -
This library is replicated in the live Commerce Cloud instance together with the product catalog. As far as Commerce Cloud is concerned, this means there is no difference when it comes to delivering editorial content to the live state.
Commerce Cloud thus represents the main component in this architecture. It delivers the content that has been created and/or maintained in FirstSpirit to the customer and provides all shop functions. There is only one loose link between the two systems; they primarily work in parallel with one another. If the FirstSpirit server is shut down because of maintenance work, for example, this has no effect on Commerce Cloud.
1.3. Concept
The ContentConnect module enables editorial content to be maintained in FirstSpirit and this to be transferred into Commerce Cloud via deployment. For this, the processing of content in both systems must be coordinated and be mutually compatible. The sub-chapters below describe the underlying concept used to achieve this compatibility.
1.3.1. Pages
Similar to FirstSpirit, the pages in Commerce Cloud are based on a structure of various components. To enable editorial content to be exchanged between both systems, these components must be coordinated.
Within the reference project ContentConnect Reference Project included in the delivery, the slots are represented by the content areas of a page template. Sections can be added to them; each one corresponds to an asset and, depending on the use cases, also has a slot configuration (see figure Page Rendering). With the aid of these configurations, it is possible to define which target group can see the corresponding content, or for how long this remains visible, for example. Each slot configuration refers to exactly one asset.
With FirstSpirit assets can thus be generated that are displayed on a page via slots.
1.3.2. Preview
The integration effected by the ContentConnect module only allows FirstSpirit to generate and maintain editorial content and to publish it in the form of assets. Commerce Cloud, however, continues to determine the framework of a page, whose slots integrate the generated assets.
To present the preview of a page, FirstSpirit therefore determines its current view in Commerce Cloud Storefront and downloads the HTML. The slots it contains are uniquely labeled with HTML comments. FirstSpirit substitutes these areas with the appropriate editorial content and displays the result in the preview.
1.3.3. Velocity
Salesforce provides the Content Integration API (CI API)
as an alternative to the slot-based approach described previously. This API enables Velocity fragments to be evaluated on the Salesforce side, and therefore provides an easy way of implementing business logic on a page. In addition, it affords editors more control over the page layout than they have in the slot-based approach. The Velocity fragments, including the business logic, are maintained within FirstSpirit.
1.3.4. Languages
Editorial content is maintained in different languages on both the Salesforce and the FirstSpirit side. For integration, an assignment between the languages of both systems is therefore required. For this, a convention has been adopted for the languages used in the reference project, which relates to their abbreviation defined in FirstSpirit. This is oriented towards the existing languages in Salesforce and ensures every abbreviation is designated in accordance with the formula LANGUAGE CODE_COUNTRY CODE
(see figure Languages). The language code corresponds to ISO 639 and the country code to ISO 3166.
Furthermore, in the project it is ensured that the FirstSpirit master language is assigned to the default language in Salesforce.
This information is presented in more detail in the Generation and Homepage chapters.
1.3.5. Generation & deployment
It is Commerce Cloud that transfers the content created in FirstSpirit to the live state. The content must be made available to Commerce Cloud in the form of two XML files, which have been created during generation. While one of these files contains all the slot configurations created in the FirstSpirit project, the second contains all the assets.
The WebDAV deployment transfers both XML files together with the generated media to Commerce Cloud and stores them in the Commerce Cloud storage location. From this point, they are then imported via a job schedule, which is initiated by means of the FirstSpirit schedule.
1.3.6. Delete
The content of a FirstSpirit project can be changed or deleted at any time as part of the usual editorial process. These changes have to be applied to Salesforce. In the same way that new content is transferred, it is also deleted by means of deployment.
A current time stamp is added to all assets and slot configurations at the start of each full generation. Therefore, its time stamp diverges from the time stamps of the content, which is still present in Salesforce, but which has already been deleted in the FirstSpirit project. The last action of the generation schedule identifies the assets and slot configurations with an outdated time stamp and triggers their deletion.
1.4. Technical requirements
The ContentConnect module has the following technical requirements:
-
FirstSpirit version: FirstSpirit (isolated or legacy mode) since 2020-01
-
Commerce Cloud e-commerce shop system
-
Storefront Reference Architecture version 6.2.0
-
Crownpeak LINK Cartridges
int_espirit
,int_espirit_sfra
resp.int_espirit_sg
version 22.1.0 -
Open Commerce API version 22.10 or higher
-
Latest JSTL version (provided with the JSTL module)
-
Java 11 or higher
2. Components
ContentConnect consists of various components. The functionality of these components is described in the following sub-chapters.
2.1. ContentConnect module
The ContentConnect module is the main component for connecting FirstSpirit and Commerce Cloud. It is extremely important for bidirectional data exchange between the FirstSpirit server and Commerce Cloud.
The module provides a report in both SiteArchitect and ContentCreator, showing the product information obtained from Commerce Cloud. The module determines which data is required and transfers it to the report when an editor initiates a query prompting it to do so. The data that is returned can then be used again for creating and maintaining editorial content.
If a generation is performed once the content has been created, the module combines the content in the form of two XML files. The WebDAV module then transfers the files to the Commerce Cloud storage location. Commerce Cloud reads out the data from this location and transfers it to the live state.
The ContentConnect module provides an API for the implementation of product-specific functions. More information is available in the accompanying Javadoc documentation. |
2.2. WebDAV module
The editorial content is created and edited in FirstSpirit. In this case, however, it is Commerce Cloud that transfers it to the live state. This means that the content has to be made available to Commerce Cloud. For this purpose, the ContentConnect module creates one XML file for the library and one for the slot configuration as part of a deployment. These files must be transferred to Commerce Cloud along with the referenced media.
This is the task of the WebDAV module, which acts as a link between FirstSpirit and Commerce Cloud and stores the data in the Commerce Cloud storage location. Commerce Cloud reads out the data from this location.
2.3. JSTL module
Within the reference project, JSTL is required to preview certain pages. The JSTL module enables this. However, the module only needs to be installed on the FirstSpirit Server if JSTL has not yet been integrated on the server in any other way.
2.4. Commerce Cloud Cartridges
The delivery includes the three cartridges int_espirit
, int_espirit_sfra
, and int_espirit_sg
. They work with all locales and are not subject to any particular restrictions in this respect.
- int_espirit
-
The
int_espirit
cartridge contains scripts, which are used in the other two cartridges. The functions provided are used, for example, to map Commerce Cloud render templates on FirstSpirit page templates and thereby to make it possible to create category and product pages (see Product Page Template Mapping, Category Page Template Mappings, and Category and product pages). - int_espirit_sfra
-
The
int_espirit_sfra
cartridge overwrites a few templates from the Storefront Reference Architecture in order to enable a preview on the FirstSpirit side. The cartridge also contains the following controllers:-
Common: The
Common
controller provides the standard components of a Salesforce shop as individual widgets. -
Content: The
Content
controller receives the Velocity fragments maintained in FirstSpirit and returns the HTML rendered on this basis. -
CategorySearchResult: The
CategorySearchResult
controller determines the products of a sub-category and provides these as a separate widget. -
Product: The
Product
controller provides the widgets of a product detail page and controls how the product detail page is displayed when the website is live. -
RenderTemplate: The
RenderTemplate
controller determines the Commerce Cloud render template for a specified product or a specified category. It uses the options of the Storefront Reference Architecture and draws on the functions of theint_espirit
cartridge. -
Search: The
Search
controller enables FirstSpirit category detail pages to be displayed in the live state.
-
- int_espirit_sg
-
For shops that are not based on the Storefront Reference Architecture, the
int_espirit_sg
cartridge contains a corresponding implementation of theRenderTemplate
controller.
3. Commerce Cloud - Installation and configuration
Various components must be installed and configured in order to use the functions of the ContentConnect module. The following sub-chapters explain the necessary steps for installing and configuring components in Commerce Cloud. The corresponding import file is located in the data
folder.
3.1. Setting up the cartridges
The delivery includes three cartridges, which must be transferred to Commerce Cloud initially. Different methods for this are described in the Commerce Cloud documentation under Salesforce B2C Commerce 22.10 ➔ Developing Your Site>Development Components>Cartridges.
Next, the int_espirit
cartridge must be added to all sites that are to receive FirstSpirit content. You can find relevant instructions in the Commerce Cloud documentation under Salesforce B2C Commerce 22.10 ➔ Developing Your Site>Development Components ➔ Register a Cartridge. Sites that are set up on the Storefront Reference Architecture and are maintained in FirstSpirit also require int_espirit_sfra
in their cartridge path. However, if a site is based on SiteGenesis, its cartridge path must include int_espirit_sg
.
The three cartridges work with all locales and are not subject to any particular restrictions in this respect. |
3.2. Import of the zip file importExamples
For the setup of the job schedules and the content cleanup as well as for the slot configurations various files are required, which are stored in the file importExamples.zip. The zip file is included in the metadata directory within the delivery and must be added to the Commerce Cloud. To do so, it must be imported via the page. The files contained in it require different configuration steps, which are explained in detail in the corresponding subchapters.
3.3. Setting up the job schedules
To import the content and slot configurations generated by FirstSpirit into Commerce Cloud, a job schedule must be created in Commerce Cloud for each site. Therefore, the metadata directory of the delivery contains the zip file importExamples.zip, which requires an import into the Commerce Cloud as described previously.
The jobs imported with the zip file have the job IDs FirstSpirit-Import-RefArch
and FirstSpirit-Import-RefArchGlobal
by default. The ID ensures the uniqueness of the jobs for the different sites and can be adjusted as required on the page. It is recommended to include the ID of the respective site in the corresponding job ID to ensure uniqueness.
The job schedules configured in the file consist of three job steps. These are of the types Import Content
, Import Content Slots
, and Rebuild Search Index
. All three job steps initially have the scope RefArch
or RefArchGlobal
, which must be changed to the appropriate site. In addition, these define different parameters whose default values can be kept mostly. Only the parameters WorkingFolder
and FileNamePattern
need to be adapted to the specific project. The editing dialog opens by clicking on the job step’s name.
- WorkingFolder
-
The parameter
WorkingFolder
specifies - relative to theIMPEX
directory - the path to the directory containing the XML files generated by FirstSpirit. Its value must be identical for both job steps. - FileNamePattern
-
The parameter defines the name of the XML files generated by FirstSpirit. In the case of the
ImportContent
job step, it must have thefs_import_library.xml
value and for theImportContentSlots
job step, it must have thefs_import_slot_configuration.xml
value.
General information about creating job schedules can be found in the Commerce Cloud documentation in chapter dministering Your Organization ➔ Jobs ➔ Creating Jobs. The three job steps and their parameters are described in the Commerce Cloud documentation in the chapters ImportContent, ImportContentSlots, and SearchReindex. |
3.4. Setting up content cleanup
In order to delete assets and slot configurations managed and deleted by FirstSpirit from Commerce Cloud too, the following steps must be taken:
Importing the user-defined system object attributes
For the persistence of time stamps assigned during generation, content cleanup uses the user-defined fsGenerationTime
attribute as part of assets and slot configurations. This must initially be added to the system objects (content and slot configurations). To create the user-defined system object attributes, the zip file importExamples.zip must be available in the Commerce Cloud. It is stored within the metadata directory, which is included in the delivery. Its provision is done via the previously described import process.
Create additional custom attributes for assets
The number of content assets to be deleted can be additionally restricted on the basis of any other custom attributes. If this is desired, appropriate attributes must be created for content assets. A description can be found in the Commerce Cloud documentation under Salesforce B2C Commerce 22.10 ➔ Administering Your Organisation>Business Objects ➔ Creating Custom Attributes for Business Objects.
Generating search refinements for assets
For the newly created fsGenerationTime
attribute and the additionally created custom attributes, a Commerce Cloud Search Refinement is to be generated. The Commerce Cloud documentation describes this under Merchandising Your Site ➔ Content Assets ➔ Working with Content Assets ➔ Creating Content Search Refinements.
After importing the user-defined system object attributes and creating the search refinement, it is necessary to rebuild the site’s search indexes. |
3.5. OC API Settings
The OC API is used for aspects including reports and deployment. Therefore, the corresponding permissions must be set in Salesforce for the Client ID
that is used.
The rights adjustments described below can also be found in the separate files Shop OCAPI-Settings and Data OCAPI-Settings. |
The Client ID
that is used requires permission to execute GET queries via the ShopAPI for the resources indicated below. These must be implemented in the global or site-specific context according to the use case.
-
/products/*/variations
-
/products/*
-
/product_search/variations
In addition when using content cleanup:
-
/content_search
Permissions are additionally required to execute GET, POST, and DELETE queries via the DataAPI for the resources indicated below. They are to be exclusively defined in the global context.
-
/catalogs
(GET only) -
/catalogs/*/categories
(GET only) -
/jobs/*/executions
(GET & POST) -
/jobs/*/executions/*
(GET only)
In addition when using content cleanup:
-
/sites/*/slot_configuration_search
(POST only) -
/libraries/*/content/*
(DELETE only) -
/sites/*/slots/*/slot_configurations/*
(DELETE only)
Furthermore, the usage of the Sorting Rules requires the following definition:
-
/sites/*/sorting_rule_search (nur POST)
If, as an option, workflows are to be used for deleting library folders and folder assignments, permissions are then required to execute DELETE queries via the DataAPI for the following resources:
-
/libraries/*/folders/*
-
/libraries/*/folder_assignments/*/*
3.6. Slot configurations
The templates from the int_espirit_sfra
cartridge are used to add new slots to the site. Therefor, the delivery provides the zip file importExamples.zip with slot configurations for these slots. It is stored within the metadata directory, which is included in the delivery. The provision of the zip file slotConfigurations.xml in the Commerce Cloud is done via the previously described import process.
4. FirstSpirit - Installation and configuration
Various components must be installed and configured in order to use the functions of the ContentConnect module. The following sub-chapters explain the necessary steps for installing and configuring components in FirstSpirit.
4.1. Installing the modules
The ContentConnect delivery contains three modules that must be added to the FirstSpirit server. To install the modules, open the ServerManager
and select .
The main panel contains a list of all the modules installed on the FirstSpirit server. Click Install, then select the contentconnect-fsm-<version number>.fsm file provided first, followed by the WebDavDeployment-<version number>.fsm and jstl.fsm files. Each time you make a selection, click Open to confirm it. Once installation has been successfully completed, the folders ContentConnect
, WebDavDeployment
and JSTL
are added to the list. Each of these must be given All permissions
.
The JSTL module only needs to be installed on the FirstSpirit Server if JSTL has not yet been integrated on the server in any other way. |
After any module installation or update, the FirstSpirit server needs to be restarted. |
4.2. Using WebDAV with https
To use the WebDAV server with https
instead of http
, it is not necessary to perform any additional configuration work. However, a local certificate authority managed by the company is normally used for https
. The certificate in question, including the entire chain up to the certificate on the WebDAV server, must be made available to the FirstSpirit server’s JVM.
The JVM expects public certificates of this kind to be in the form of a |
Using the command below, import the public root or intermediate certificates into a JKS
file and select Yes in answer to the question whether the certificate is to be trusted. You must repeat this process for each certificate.
keytool -import -file cert1.crt -keystore truststore.jks –storepass changeit
Copy the Trust Store
that is generated into the directory of your FirstSpirit server and add the following lines to the file
.
wrapper.java.additional.100=-Djavax.net.ssl.trustStore=conf/truststore.jks
wrapper.java.additional.101=-Djavax.net.ssl.trustStorePassword=changeit
wrapper.java.additional.102=-Djavax.net.ssl.trustStoreType=JKS
The parameters must be activated by restarting the FirstSpirit Server. |
If the WebDAV server is expecting mutual SSL authentication, you must use the following calls to create and sign a client certificate as a first step.
openssl genrsa -out private.key 2048
openssl req -new -key private.key -out request.csr
The file request.csr
is sent to the certificate authority, which responds with the file cert.crt
. The private key, the public certificate, and the certificate from the certificate authority must then be collected in a Key Store
to be read by the JVM
.
cd firstspirit5/conf
openssl pkcs12 -export -in public.crt -inkey private.key \
-out clientcert.p12 -CAfile authority.crt
If the certificate chain consists of one or more intermediate certificates, you can import them via keytool
.
keytool -import -file intermediate1.crt -trustcacerts \
-keystore clientcert.p12 -storepass changeit
The Key Store
can be transferred to the JVM
of the FirstSpirit Server by adding the following lines to .
wrapper.java.additional.103=-Djavax.net.ssl.keyStore=conf/clientcert.p12
wrapper.java.additional.104=-Djavax.net.ssl.keyStorePassword=changeit
wrapper.java.additional.105=-Djavax.net.ssl.keyStoreType=PKCS12
4.3. Project import
A part of the StarterPackage included in the delivery is the reference project ContentConnect Reference Project, which must be installed on the FirstSpirit server. To do this, open the import dialog in the ServerManager
via the menu item and click the Lokal button to select the
ContentConnectReferenceProject.tar.gz
file from your local data system. Then assign a project name and description and confirm the import with Yes. After successful installation, the project is added to the list in the main panel (see figure Imported project in the ServerManager).
In addition to the standard groups |
4.4. Configuring the project component
A project-specific configuration is required in order to use the ContentConnect module. It is set up using the project component, which is already added to the reference project supplied.
To configure the project component, open the ServerManager
and select . A list of all existing project components is displayed in the main panel. Select the entry
ContentConnect Project Configuration
and click Configure to open the associated dialog (see figure Configuration dialog for the project component).
The subsequent configuration is used by the module services. The service and all running clients must be restarted each time the configuration is changed. Otherwise, the change in question will not be applied either to the services or to the clients. |
- Base URL
-
Start by entering the
Base URL
, which is derived from the URL of the Commerce Cloud instance and the ID of the site being used:https://<SUBDOMAIN INSTANCE>.demandware.net/s/<SITE ID>
Based on this structure, a unique connection between the FirstSpirit project and the Commerce Cloud site is always guaranteed.
The
Base URL
field is a mandatory field.
To avoid problems concerning the certificate, it must be ensured that the subdomain does not contain any periods in its name. |
- Storefront Hostname
-
This configuration field is optional and should only be filled in if the hostname of the
Storefront Base URL
in the Project settings differs from the hostname of theBase URL
configured in this dialog. In this case, the hostname including the protocol of theStorefront Base URL
should be entered here.Example:
https://<DIFFERENT SUBDOMAIN INSTANCE>.demandware.net/
- Client ID
-
The
Client ID
is also a mandatory field. This is required in order to be able to use theOpen Commerce Shop API
.
The |
- Password
-
The components of the ContentConnect API require password-based authentication against Commerce Cloud. For this reason, a password that is defined when the API client is registered with Commerce Cloud is required in addition to the client ID.
- Refinements
-
Refinements that improve product searches are defined in this configuration field. Refinements are entered as key value pairs separated using commas.
Up to the first nine key value pairs entered are used (Commerce Cloud will not accept more than nine refinements). The format of the values of the key value pairs matches the format Commerce Cloud expects for refinement values. Both multiple values and sets of values can be entered for a refinement:
|
Since a refinement is also used for category searches, two special cases need to be considered: In the first case,
In this case, there are a total of ten refinement definitions, which is not permitted. Therefore, one of the refinements from the configuration is ignored so that the product search can be filtered by a category. In the second case,
In this case, there is a duplicate definition for the |
- Locale
-
The
Locale
identifies the language and region of the current project. A maximum of one ID for an active locale that is permitted for storefront requests in the site configured at the top of the dialog may be entered. If the field is left blank, thelocale
parameter will not be used in storefront requests. - Auth User
-
If access restriction is activated in Commerce Cloud, the
storefront
user must be specified in this field. - Auth Password
-
The password belonging to the
storefront
user is specified in this field.
- Product Page Template Mapping
-
One of the functions supported by the product report is the user-friendly creation of product pages, which use the page template Product Detail Page in the reference project. To enable this, this configuration field allows Salesforce render templates to be mapped to FirstSpirit page templates. The following rules apply here:
-
The field contains either no content at all or one or more mappings.
-
If the field remains empty, the use of product pages in the project is disabled.
-
Mappings are specified using a list separated by commas: <mapping>,<mapping>
-
Each mapping is arranged as follows: <isml_template>:<fs_template>
-
To configure a page template for all ISML templates that do not have an explicit mapping, the following form must be used: default:<fs_template>
-
- Default Folder (Product Pages)
-
To create a new product page, it is essential to know where the page is to be integrated into the structure. The reference name of the Product Pages structure folder has already been entered here. All new product pages within the reference project are created in this folder. If the field is left empty, the editor must select a menu level.
- Editable Folder (Product Pages)
-
This checkbox makes it possible to specify whether an editor can change the selection made in the
Default Folder (Product Pages)
field. The function is activated initially. If it is then deactivated, the corresponding input component is hidden in the dialog for creating a category or product page. In this case, it is not possible for the editor to select or change the menu item for a newly created category or product page.
The field |
- Category Page Template Mappings
-
The mapping of page templates can be configured using this configuration field for the creation of category pages via the category report. The following rules apply here:
-
The field contains either no content at all or one or more mappings.
-
If the field remains empty, the use of category pages in the project is disabled.
-
Mappings are specified using a list separated by commas: <mapping>,<mapping>
-
Each mapping is arranged as follows: <isml_template>:<fs_template>[:fallback_category]
-
The third part of the mapping is optional and is used to specify a fallback category for category pages that are based on the specified ISML template
-
To configure a page template and an optional fallback category for all ISML templates that do not have an explicit mapping, the following form must be used: default:<fs_template>[:fallback_category]
-
We recommend using separate FirstSpirit templates for product pages and category pages. |
- Default Folder (Category Pages)
-
In the same way as with product pages, for each new category page it is essential to know where the page is to be integrated into the structure. The reference name of the Category Pages structure folder has already been entered here. All new category pages within the reference project are created in this folder. If the field is left empty, the editor must select a menu level.
- Editable Folder (Category Pages)
-
In the same way as with the
Editable Folder (Product Pages)
checkbox, here it is possible to specify whether editors can change the selection made in theDefault Folder (Category Pages)
field. The function is activated initially. If it is then deactivated, the selection option is hidden in the dialog for creating a category page. In this case, it is not possible for the editor to select or change the menu item for a new page.
The field |
- Template Instantiation Script Uid
-
Select a script to be executed before and after category or product pages are created in this configuration field (the selection of a script is optional). The create_sfcc_item_wizard script specified is used to execute project-specific actions, which are required to generate the preview. In the reference project, it marks the created category or product page as translated for all languages.
Please note that only the code from the HTML channel of the script is executed. |
- View Type Priority
-
Images of products from Commerce Cloud are always provided in a range of sizes, but an image will not necessarily have been stored for every size. For this reason, the
View Type Priority
has been provided so that you can define which image sizes you wish to incorporate, separating the information you enter with commas.In the case shown in the figure Configuration dialog for the project component, the
medium
image associated with each product is identified and is used if it exists. If there is no medium image, thelarge
image is called up, followed by thesmall
one if necessary.
As this is not a mandatory input field, it may therefore remain empty if you do not wish to define an order of priority. If this is the case, search results from a product query will be shown without an image. |
- Image Service Base URL
-
Commerce Cloud provides what is known as an
Dynamic Imaging Service
. If you wish to use it, you must specify the URL of the Image Service in the formhttp[s]://<image server host name>
at this point. Product images are then called up via the Image Service.
Specifying the |
- Use Category Search
-
Next you must decide whether the reports for products and categories should provide filtering on categories in addition to the text search field. The corresponding checkbox
Use Category Search?
is deactivated by default. In this case, the category filter is not applied in the context of the product or category search. The associated dropdown list is hidden in the report. If filtering according to category is required, the checkbox must be activated.
Filtering by category differs depending on the report used. In the report for the product search, filtering is possible across all categories. In the report for the category search, however, filtering is only possible via the top-level categories. |
- Show Category Report
-
This checkbox can be used to control the display of the category report. The checkbox is deactivated by default (i.e., only the report for product searches is active).
Figure 7. Category report - Test Configuration
-
Click the Test Configuration button to check the entries that have been entered. For this, the
Client ID
, theBase URL
and - if available - theImage Service Base URL
as well as the configurations for the product and category pages are taken into account.
4.5. Adding web components
Two web components are required for the Preview
and for ContentCreator
and have already been added to the reference project supplied. Nevertheless, they still need to be installed on an active web server. To do this, open the ServerManager
and select .
Inside the main panel, various tab pages are visible. Each tab page contains a list of the existing web components. The list contains the following entries both for the Preview
as well the ContentCreator
(see figure Web components in the project properties):
-
ContentConnect Web Component
-
FS_JSTL_WebApp
Select a Web server
on both tab pages via the selection box and start the installation by clicking the Install button. After successful installation, a dialog opens, in which the activation of the Web server
must be confirmed.
More detailed information on how to add web components is available in the FirstSpirit Documentation for Administrators.
4.6. Configuration of the web component
Part of the web component of the ContentConnect module are the Preview Proxy and the Preview Filter. Both components can be configured via the web.xml
and are described in more detail in the following two chapters.
4.6.1. Preview Proxy
If problems with cross-origin requests occur during the preview due to the same-origin policy of modern web servers, then these can be remedied by using the Preview Proxy included in the ContentConnect module.
To do this, the calls to the resources concerned must be routed via the Preview Proxy. The Preview chapter explains how this is done in the project.
The Preview Proxy is configurable via the web.xml
with the following parameter:
Parameter | Default value | Description |
---|---|---|
connection.keepalive |
60 |
Duration of maintaining a connection within the Preview Proxy in seconds. Too high values may cause problems when loading resources. |
Example
An example snippet of the web.xml
, in which the Preview Proxy’s parameter is configured and the preconfigured URL path has been adjusted, might look as follows:
<servlet>
<servlet-name>ContentConnectPreviewProxy</servlet-name>
<servlet-class>com.espirit.moddev.demandware.preview.proxy.ProxyServlet</servlet-class>
<load-on-startup>0</load-on-startup>
<init-param>
<param-name>connection.keepalive</param-name>
<param-value>120</param-value>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>ContentConnectPreviewProxy</servlet-name>
<url-pattern>/assets/*</url-pattern>
</servlet-mapping>
4.6.2. Preview Filter
The ContentConnect Preview Filter
determines the necessary information for displaying a page in the FirstSpirit preview. In the slot-based approach, it identifies the correct storefront URL for this purpose, downloads the HTML on the basis of this URL, and substitutes the slots it contains with the corresponding editorial content. If the CI API
is being used, however, it has the Velocity fragments maintained in FirstSpirit evaluated on the Salesforce side, and displays the result at the corresponding point on the page in the FirstSpirit preview.
To carry out these steps, the filter requires some information that can be configured via various parameters in the web.xml
of the added web components (for the Preview as well as ContentCreator). This information relates to various aspects, which can be divided into four groups.
The
Adjustment in the web.xml for the preview in the SiteArchitect
Beyond that, a configuration of the individual parameters is only necessary if their default values do not match the project-specific conditions. |
Storefront URL parameters
As described previously, the Preview Filter
determines the necessary information on the Salesforce side - both in the slot-based approach and when using the CI API
. It then displays this information in the FirstSpirit preview. To do this, a project-specific storefront URL is required. As this is maintained in the project settings, the Preview Filter
requires the associated input component to be specified for its query.
Parameter | Default value | Description |
---|---|---|
storefront.url.baseUrlFormField |
ps_storefrontUrlBaseUrl |
The input component for specifying the storefront’s base URL, which is extended with the page type and the ID of the element to be displayed (e.g., product, category, or asset ID). The component is maintained in the project settings. |
The syntax for the storefront base URL can be found in the Salesforce B2C Commerce 22.10 ➔ Merchandising Your Site ➔ Search Engine Optimization ➔ URL Syntax ➔ Salesforce B2C Commerce URL Syntax Without SEO chapter of the Salesforce Commerce Cloud documentation. |
As a value of the input component E.g.: https://www.mystore.com/on/demandware.store/Sites-YourShopHere-Site/ |
Changes to the project settings do not take effect straight away, as they are saved in the session of the user. They require the client to be restarted. |
Storefront Crop Marks parameters
The placeholders included in the editorial content consist of a start as well as an end comment and have the format <!-- CMS-<IDENTIFIER>-START -→
or <!-- CMS-<IDENTIFIER>-END -→
by default. However, the use of individual affixes can be activated via a toggle in the project settings, which must be added if necessary. In this case, the default values are overwritten and specific prefixes and suffixes are used instead. In order to grant the Preview Filter
access to this information, it requires the associated input components to be specified.
Parameter | Default value | Description |
---|---|---|
storefront.cropMarks. customAffixes.enabledFormField |
ps_storefrontCropMarksCustomAffixesEnabled |
The toggle in the project settings for (de)activating the use of individual affixes. |
storefront.cropMarks. opening.prefixFormField |
ps_storefrontCropMarksOpeningPrefix |
The input component in the project settings for specifying a prefix for the start comment. |
storefront.cropMarks. opening.suffixFormField |
ps_storefrontCropMarksOpeningSuffix |
The input component in the project settings for specifying a suffix for the start comment. |
storefront.cropMarks. closing.prefixFormField |
ps_storefrontCropMarksClosingPrefix |
The input component in the project settings for specifying a prefix for the end comment. |
storefront.cropMarks. closing.suffixFormField |
ps_storefrontCropMarksClosingSuffix |
The input component in the project settings for specifying a suffix for the end comment. |
Storefront protection parameters
It is possible to protect the connection to Commerce Cloud via an authentication. This can be (de)activated in Salesforce and must be applied to FirstSpirit via the corresponding toggle in the project settings. If it is activated, the required access data must also be specified. The Preview Filter
must be able to access this information and therefore requires the associated input components to be specified.
Parameter | Default value | Description |
---|---|---|
storefront.protection.enabledFormField |
ps_storefrontProtectionEnabled |
The input component in the project settings for (de)activating the authentication for the storefront URL. |
storefront.protection.userFormField |
ps_storefrontProtectionUser |
The input component in the project settings for registering the storefront user. |
storefront.protection.passwordFormField |
ps_storefrontProtectionPassword |
The input component in the project settings for the password of the storefront user. |
Storefront downloader parameters
In addition to the other parameters, which are primarily used to determine the correct storefront URL, in the slot-based approach it must be possible to control the behavior of the Preview Filter
while the HTML of the corresponding page is downloading. For this, it has different parameters, which can be maintained in the project settings. The Preview Filter
must be able to access this information and therefore requires the associated input components to be specified.
The storefront downloader parameters are used to initialize the filter in the slot-based approach. As a result, they have a fixed fallback value for cases with a missing or empty input component. |
Parameter | Default value | Description |
---|---|---|
storefront.downloader.maxConnections |
ps_storefrontDownloaderMaxConnections |
The input component in the project settings for specifying the maximum permissible number of parallel connections to Storefront. |
storefront.downloader.socketTimeout |
ps_storefrontDownloaderSocketTimeout |
The input component in the project settings for specifying the time span (in milliseconds) in which a response from Storefront is expected. |
storefront.downloader.retryCount |
ps_storefrontDownloaderRetryCount |
The input component in the project settings for specifying the maximum number of connection attempts. |
The use of the following two parameters is only recommended in exceptional cases, as they bypass the certificate check for |
Parameter | Default value | Description |
---|---|---|
storefront.downloader.certificatesCheck |
true |
Setting this parameter to |
storefront.downloader.sslWhitelist |
empty |
If the certificate check is deactivated, the host names to be excluded from the blocking are maintained via the |
Storefront Cache Parameter
The HTML of slot-based pages downloaded by the Preview Filter
is stored in a cache so that it does not have to be retrieved from the Commerce Cloud every time it is called. Such a cache exists across sessions for each project on the FirstSpirit server. This cache has some parameters that can be maintained in the project settings. The Preview Filter
must be able to access this information and therefore needs to specify the associated input components.
Like the downloader parameters, the cache parameters are used to initialize the filter in the slot-based approach. For this reason they have a fixed fallback value in case of a missing or empty input component. |
Parameter | Default value | Description |
---|---|---|
storefront.cache.maxEntries |
ps_storefrontDownloaderMaxCacheEntries |
The input component in the project settings for specifying the maximum number of elements in the cache. |
storefront.cache.refreshAfterWrite |
ps_storefrontCacheRefreshAfterWrite |
The input component in the project settings for specifying the time span (in hours) until an element in the cache is marked as obsolete. |
storefront.cache.expireAfterWrite |
ps_storefrontCacheExpireAfterWrite |
The input component in the project settings for specifying the time span (in hours) until an item in the cache is marked as removable. |
storefront.cache.excludePatterns |
ps_storefrontCacheExcludePatterns |
The input component in the project settings for specifying storefront URLs that should not be kept in the cache. The URLs are specified in the form of a list of regular expressions. |
Example
An example snippet of the web.xml
, in which two parameters of the Preview Filter are configured, might look like as follows:
<filter>
<filter-name>ContentConnectPreviewFilter</filter-name>
<filter-class>com.espirit.moddev.demandware.preview.PreviewFilter</filter-class>
<init-param>
<param-name>storefront.downloader.socketTimeout</param-name>
<param-value>ps_myCustomStorefrontDownloaderSocketTimeout</param-value>
</init-param>
<init-param>
<param-name>storefront.downloader.retryCount</param-name>
<param-value>ps_myCustomStorefrontDownloaderRetryCount</param-value>
</init-param>
</filter>
4.7. Resolutions
The reference project ContentConnect Reference Project has different sections, with which images can be integrated on the various pages. It should be possible for the editor to crop the images to a certain image section. This function is activated by specifying a resolution.
$CMS_REF(st_picture, resolution:"RESOLUTION")$
For the reference project, the following resolutions are required: BANNER
, SLIDE
, GRID_ELEMENT_HIGH
, GRID_ELEMENT_WIDE
, GRID_ELEMENT_SQUARE
, IMAGE_MAP
, ARTICLE_TEASER_IMAGE
and TECHNOLOGY_IMAGE
. They are already applied within the ServerManager
in the area and specified in the corresponding areas in the sections.
4.8. Deployment schedule
To transfer the content created in FirstSpirit to the Commerce Cloud storage location, the reference project supplied has a schedule, which contains the actions specified below (see figure Generation schedule actions). A description of the individual actions is provided in the subsequent sub-chapters.
More information on creating a schedule is available in the FirstSpirit Documentation for Administrators.
4.8.1. Initialize SFCC deployment
The first step is to initialize the deployment. This involves setting up content cleanup. While this is under way, a time stamp prior to the generation is created. This time stamp is used by the cleanup action in the last step of the schedule to delete outdated assets and slot configurations. It is for this reason that the schedule contains the action Salesforce Commerce Cloud Initializer
:
To use content cleanup, the initialization must be the first action of the schedule. Otherwise this can lead to inconsistencies in the data inventory. |
4.8.2. Content preparation - Full generation
To deploy the content that is relevant to Commerce Cloud, it must be determined from the project first. This requires a full generation to be carried out, generating all the referenced media in the correct resolution. The full generation also generates the XML collectors initialized in the project settings and fills them on the basis of the xmlCollector calls in the templates.
The schedule therefore has the generation action Content Preparation
in whose Properties
the following options are activated (see figure Content preparation action):
-
Perform FullGeneration
-
Clear generation directory beforehand
-
Generate Media in the generation directory
The defined Prefix for absolute paths
/firstspirit
is required for the WebDAV deployment action.
It is only possible to use the WebDAV module in conjunction with the default URL creator. To generate the path, the entry |
The template sets for all the languages present in the project are also selected on the Extended
tab page. In addition, the variable dwre_xmlGeneration
is added, which contains the value false
. This is set to the value true
in the subsequent XML Import File
actions and ensures that the XML files for the slot configurations and assets are only created once the generation is complete. The XML template in the project controls the process of generating the XML file.
4.8.3. XML import file - Partial generations
Commerce Cloud expects all data that is transferred to it to be in the form of XML files. For this reason, the information determined during the full generation must be read out of the XML collectors that are generated. In this case, the information must instead be written to an XML file that has to be created each time.
For each XML collector initialized in the project settings, the schedule provides another generation action. In contrast to the Content Preparation
action, these are, however, partial generations. In their Properties
, the option Execute partial generation for following start nodes
is therefore activated. As a starting point, one of the page references based on the XML template is used (see figure Partial generation).
The variable dwre_xmlGeneration
, which contains the value true
, is also added to the Extended
tab page for each of these actions. Together with the start node selected in each case, this ensures that the selected page reference is not generated until this point in time. This means that all the information required for creating the XML file will be available when this happens and it will not be possible for any gaps to appear. The XML template in the project controls the process of generating the XML file.
4.8.4. WebDAV deployment
Next, the XML files generated by means of the partial generations must be transferred to Commerce Cloud. They are published via a script action, for which the following parameters are defined in their Properties
:
- url
-
The
URL
specifies the host and the path on the WebDAV server. It always has the following structure:https://<SUBDOMAIN INSTANCE>.demandware.net/on/demandware.servlet/webdav/Sites/Impex/…/<PREFIX>/<SITE ID>
The path points to the location where the XML file in question is expected to be during the import. It must refer to an existing directory. |
- user
-
A technical user who is authorized to use the WebDAV interface is required in order to transfer the data. This user must have write permissions and must be specified by name here.
Further information about these rights can be found under Administering Your Organization ➔ Permissions, Users, and Roles ➔ Roles and Permissions ➔ Create a Role in the Salesforce documentation.
- password
-
A password is also required for the user specified in the previous step.
The technical user is subject to the password conditions defined by Commerce Cloud, which require the password to be changed at least every quarter. The parameter value must be changed each time this is carried out. |
- mediaurl
-
The media folder generated during the generation process, and its content, must be transferred to a separate directory so that Commerce Cloud can perform the import. This directory is defined using the parameter
mediaurl
. Themediaurl
always has the following structure:https://<SUBDOMAIN INSTANCE>.demandware.net/on/demandware.servlet/webdav/Sites/Libraries/<SITE ID|LIBRARY ID>/default/<PREFIX>
The |
If a private library is being used, it is necessary to specify the site ID instead of the library ID in the path. |
- srcprefixdir
-
If only one particular directory is transferred to Commerce Cloud, it can be specified in relation to the root node of the generation directory using the optional parameter
srcprefixdir
. If the parameter is not defined, or no value is saved for it, the entire generation directory will be transferred. - purge
-
This parameter is optional and may only have the value
true
orfalse
. Iftrue
is set, all the files and directories under the specifiedURL
will be deleted before the transfer starts. If the parameter is set tofalse
or no value at all, all the existing files and directories under the specifiedURL
will be retained. New data will either be added or, in the case of existing data, overwritten. - javax_net_ssl_keyStore (optional)
-
This parameter can be used to specify a dedicated Java certificate file for WebDAV deployment.
- javax_net_ssl_keyStorePassword (optional)
-
The password of the Java certificate file.
- javax_net_ssl_keyStoreType (optional)
-
The type of the Java certificate file, e.g.
jks
.
The WebDAV deployment must not be executed in the event of an error. |
4.8.5. Trigger SFCC import job schedule
Following the publication of the created XML files via WebDAV deployment, the created job schedule is executed. In Salesforce, the job schedule triggers the import of the generated content and slot configurations into Commerce Cloud. The ContentConnect module provides the Salesforce Commerce Cloud Importer
schedule action for this purpose:
The action loads a configuration dialog, in which two parameters must be defined in addition to a freely assignable name.
- Import Job ID
-
This field contains the ID of the created job schedule.
- Timeout
-
The value in this field displays the time span in seconds, in which the status of the job schedule will be queried every second. If the job schedule has not completed in the specified time span, this schedule action is indicated as having an error. The default value is 10 seconds.
As the |
4.8.6. Salesforce Commerce Cloud Cleanup
Once the created job schedule has been executed, content cleanup is executed. All outdated assets and slot configurations are queried by the OC API and then deleted. The ContentConnect module provides the Salesforce Commerce Cloud Cleanup
schedule action for this purpose:
In addition to a freely assignable name for this schedule action, the associated configuration dialog contains the following parameters:
- Use different site
-
Content cleanup uses a Commerce Cloud site to find the content assets and slot configurations to be deleted. The checkbox
Use different site
allows the use of content cleanup for a site other than the configured site.
- Site Id
-
If the
Use different site
checkbox is active, the Commerce Cloud site to be used for content cleanup must be specified in this field. -
This checkbox allows to enable/disable the content cleanup of assets.
- Library Id
-
The ID of the Content Library from that Content Assets are deleted must be entered in this field. In the case of a private library, the library ID corresponds to the site ID.
- Additional refinement(s)
-
In this field, attribute names and values can be specified for further filtering of the content assets to be deleted. The specification must have the following form:
ATTRIBUTE_NAME=ATTRIBUTE_VALUE [; ATTRIBUTE_NAME=ATTRIBUTE_VALUE] ...
The attribute values can contain the following parameters:
Parameter Replacement by ${projectId}
The ID of the generated FirstSpirit project
${projectName}
The name of the generated FirstSpirit project
The specified attributes must exist as custom attributes in the Commerce Cloud and have been filled with values via the FirstSpirit generation before the filtering described here can be used. |
-
This checkbox allows the de-/activation of the content cleanup from Slot configurations.
- Filter query
-
This field is used to filter the slot configurations to be deleted. A filter is specified as a query document in JSON format. Within the query, the parameters of the field Additional refinement(s) can be used, as the following example of a TextQuery illustrates:
"text_query": { "fields": ["c_fsProjectId"], "search_phrase": "${projectId}" }
If the
Filter query
field remains empty, the ContentConnect module uses a MatchAllQuery, whereby the slot configurations to be deleted are not further filtered.
To avoid inconsistencies in the database or data loss, the action |
Since the |
4.9. Workflows
Content is released, deleted, and published by editors within the supplied reference project ContentConnect Reference Project via workflows. For this reason, it contains a publish workflow, as well as the BasicWorkflows, which can be used as an alternative to project-specific workflows.
Installing the BasicWorkflows module
Before using the workflows, you must install the BasicWorkflows module on the FirstSpirit server and activate the web component. The necessary steps are the same as for installing the other modules and activating the associated web components. However, the web component for the BasicWorkflows is only needed on the ContentCreator
tab page.
In addition, to use BasicWorkflows in the ContentCreator, the provided BasicWorkflows Status Provider
must be selected in the area within the
ServerManager
. In the reference project ContentConnect Reference Project, this setting has already been applied (see figure Element Status Provider).
In addition, in the area, the
Workflow for deleting elements
is preselected. As a result, any action to delete elements within the project (Del button, delete icon) is executed via this workflow. The native (independent of a workflow) deletion of elements is therefore not available - not even for the administrator.
Templates
The BasicWorkflows and the workflow supplied with the StarterPackage require different templates. Usually, these need to be imported for the BasicWorkflows via the context menu in the FirstSpirit project used. However, they are already available in the reference project and importing the templates is therefore not necessary.
The publish workflow initiates the deployment schedule and requires its name for this. If this deviates from the Generate and deploy to SFCC expression, the value of the |
Permission assignment
In the final step, the workflows must be authorized in the individual stores so that they can be executed on FirstSpirit elements. To do this, select from the context menu of the stores' root nodes to call up the permission assignment. This step has also already been carried out in the reference project and is therefore omitted.
The permissions for executing workflows set on the stores' root nodes relate to the |
You can find more detailed information in the BasicWorkflows Documentation.
4.10. Project settings
There is some essential project-specific information that needs to be entered for the connection between FirstSpirit and Commerce Cloud (see figure Project settings). It is entered using the project settings form and must be specified within the reference project.
Changes to the project settings do not take effect straight away, as they are saved in the session of the user. They require the client to be restarted. |
- Storefront Base URL
-
The field is used to specify the storefront’s base URL, which is extended with the page type and the ID of the element to be displayed (e.g., product, category, or asset ID). It has the following format:
https://<SUBDOMAIN INSTANCE>/on/demandware.store/Sites-<SIDE ID>-Site
More information on the storefront base URL is available in the Commerce Cloud Documentation in the chapter Merchandising Your Site ➔ Search Engine Optimization ➔ URL Syntax ➔ Salesforce B2C Commerce URL Syntax Without SEO.
As a value of the storefront base URL, only up to the locale, not the entire URL must be entered in accordance with its specified format. Example: |
- SFCC Content Asset ID Prefix
-
To uniquely identify the content assets generated by FirstSpirit, a prefix for the content asset ID is to be defined at this point.
- Preview Protection (BasicAuth)
-
Within Commerce Cloud, it is possible to protect access to the storefront by activating the
Online (protected)
site status. If this restriction is applied, thestorefront
user must be specified in FirstSpirit. Activating the toggle displays theUser
andPassword
fields. - User
-
If access restriction is activated in Commerce Cloud, the
storefront
user must be specified in this field. - Password
-
The password belonging to the
storefront
user is specified in this field. - StarterPackage Version
-
This field is solely utilized to display the version of the used reference project.
- Enable Custom Affixes
-
The toggle makes it possible to use individual affixes for the HTML comments included in the templates, which are used to indicate the content to be substituted for the preview. These have the format
<!-- CMS-<IDENTIFIER>-START -→
or<!-- CMS-<IDENTIFIER>-END -→
by default. When the toggle is activated, all four affixes are overwritten and the default values are therefore no longer taken into account. The specific values can then be specified using the following fields. If one of the form fields is missing even though the toggle is activated, an empty string is used for the corresponding affix.
For the individual affixes, the format Spaces that are entered in the configuration fields in front of or behind an individual affix are ignored. If the toggle is activated without at least one affix defined, this can lead to unexpected behavior. |
Within the reference project, all HTML comments have the standard format. For this reason, the template for the project settings does not include the toggle or the form fields for the use of individual affixes. |
- Opening Prefix/Opening Suffix
-
Together with the identifier, the opening prefix and the opening suffix form the start HTML comment and mark the beginning of the content to be substituted.
- Closing Prefix/Closing Suffix
-
Together with the identifier, the closing prefix and the closing suffix form the end HTML comment and mark the end of the content to be substituted.
- Storefront-URL Controller Form Field
-
To determine the storefront URL, the ContentConnect Preview Filter must know which controller (e.g., Home, Page or Search) it needs to address. This information generally depends on the page to be displayed, which is why the Preview Filter reads it out from an input component on the preview page form. The Preview Filter uses the
pt_storefrontUrlController
field by default. This behavior can be configured in the project settings using theps_storefrontUrlControllerFormField
field, in which the name of the form field to be read out is entered if required.
Within the reference project, all page templates have the |
- Storefront-URL Context ID Form Field
-
In addition to the controller, the ContentConnect Preview Filter may in some cases require an ID (such as a product, category, or content asset ID); it also determines this on the basis of the page form. There is the option of configuring the corresponding form field in the project settings using the
ps_storefrontUrlContextIdFormField
field. The Preview Filter reads out thept_storefrontUrlContextId
component by default.
Within the reference project, all page templates have the |
Additionally, the template is used to initialize two XML collectors and a Product Manager, which are used in the other page and section templates of the project. These page and section templates define which data is to be transferred to Commerce Cloud. During the generation process, the data is collected on the basis of these definitions and the XML collectors are filled.
If there are project-specific requirements for the XML collectors, then these can be adapted using the methods from the Information on calling up the Product Manager is contained in the Javadoc for the |
5. Use cases
The ContentConnect module provides various options for accessing Commerce Cloud content and for using this in FirstSpirit. These functions are equivalent in both clients and are described in the following using the reference project ContentConnect Reference Project supplied in the form of use cases. The description of each use case is aimed at editors as well as FirstSpirit developers.
5.1. Preview
To display the preview of a page, the ContentConnect Preview Filter determines the necessary information on the Salesforce side. In the slot-based approach, it identifies the correct storefront URL for this purpose, downloads the HTML on the basis of this URL, and substitutes the slots it contains with the corresponding editorial content. The slots are uniquely labeled with HTML comments and are represented in FirstSpirit by the content areas of a page template. If the Content Integration API
is being used, however, the Preview Filter has the Velocity fragments maintained in FirstSpirit evaluated on the Salesforce side, and displays the result at the corresponding point on the page.
Editor view
The editorial content is created and maintained in FirstSpirit. Editors have the standard tools available to them and do not require any additional knowledge. From the view of an editor, the content of both systems is automatically merged and displayed in the preview or in the ContentCreator.
Developer view
The pages within the reference project that is supplied are based on the slot-based approach as standard. However, as is the case in the example of the category detail page, it is also possible to use the CI API
. The two approaches are fundamentally different from one another, and whichever one is being used is automatically taken into account by the ContentConnect Preview Filter when a preview is being generated.
Slot-based approach
Within the reference project supplied, the slots from Salesforce are represented by the content areas of the page templates. Sections can be added to them; each one corresponds to an asset and, depending on the use case, also has a slot configuration. To display a page in the preview, the slots contained in the downloaded HTML are substituted by the editorial content.
For the substitution, all content relevant for the preview must be labeled with unique HTML comments. From a technical point of view, these can occur in every template but are only included in page templates in the reference project. Each consists of a start as well as an end comment and has the format <!-- CMS-<IDENTIFIER>-START -→
or <!-- CMS-<IDENTIFIER>-END -→
by default.
The use of individual affixes can be activated for HTML comments via a toggle in the project settings, which must be added if necessary. In this case, the default values are overwritten and specific prefixes and suffixes are used instead. |
These exact same HTML comments must also be inserted into the storefront page by the Salesforce developer, and the slots to be substituted must be indicated. It is important to make sure that the identifier in the FirstSpirit template and in the storefront page match. Otherwise, there is an error in the presentation of the preview. |
Using the Content Integration API
The Content Integration API
enables Velocity fragments to be evaluated on the Salesforce side. These fragments are maintained in the FirstSpirit templates and substituted when a page is displayed in the preview. For this purpose, the Preview Filter receives the results of the evaluation conducted on the Salesforce side and inserts them at the corresponding points on the page. The Velocity fragments must also be labeled with unique HTML comments to enable the Preview Filter to carry out this step. The comments consist of a start comment and an end comment, and must always use the following format: <!-- CMS-VELOCITY-<IDENTIFIER>-START -→
or <!-- CMS-VELOCITY-<IDENTIFIER>-END -→
.
Substitutions with regular expressions
Should further substitutions be additionally required, specific regular expressions can be defined. These have their own syntax and always take the following form:
<!-- CMS-REGEX-PATTERN-START -->
regex-match="<REGEX>"
regex-value="<REPLACEMENT>"
<!-- CMS-REGEX-PATTERN-END -->
While the expression regex-match
saves the regular expression, it is the expression regex-value
that specifies the content, which will substitute all regex matches in the document. Both expressions are to be summarized as an instruction by the HTML comments <!-- CMS-REGEX-PATTERN-START -→
and <!-- CMS-REGEX-PATTERN-END -→
.
With respect to the reference project, for example in the Preview Generation format template, this enables additional CSS to be integrated into each page template or any link on the Homepage to be substituted:
$-- Set Bootstrap CSS--$
<!-- CMS-REGEX-PATTERN-START -->
regex-match="<\/head>"
regex-value="$CMS_IF(#global.is("PREVIEW"))$$CMS_RENDER(template: "preview_css_additions")$$CMS_END_IF$</head>"
<!-- CMS-REGEX-PATTERN-END -->
$-- Change Homepage Reference --$
<!-- CMS-REGEX-PATTERN-START -->
regex-match="href=("|').*.home[?]"
regex-value="href="$CMS_REF(pageref:"homepage")$""
<!-- CMS-REGEX-PATTERN-END -->
If a convert2 is used within the regular expressions applied, it is important to make sure that all special characters are correctly resolved. It may be necessary to adjust the conversion rule, in particular in conjunction with the dollar sign ( |
Please note that the replacement of the URL depends on the new storefront URL. The settings can be found under the menu item |
ContentConnect Preview Language
The following pattern is needed to configure the display language in the ContentCreator:
$-- Set Preview Language --$
<!-- CMS-PARAM-PREVIEWLANG-START -->
$CMS_VALUE(set_previewLang)$
<!-- CMS-PARAM-PREVIEWLANG-END -->
The format of the language abbreviation that is provided within the pattern is explained by the paragraph Determining the locale. If the Preview Filter cannot find this pattern it will use default
as a value for the preview language.
ContentConnect preview proxy
If problems with cross-origin requests occur during the preview due to the same-origin policy of modern web servers, then these can be remedied by using the preview proxy included in the ContentConnect module.
In the supplied reference project, this is the case when loading the Font Awesome font via an integrated CSS file, for example. If the preview proxy is not used, a cross-origin request will be executed when the font is loaded, which will be blocked by the same-origin policy.
To manage the loading of the resources in question via the preview proxy and therefore avoid cross-origin requests, the Preview Generation format template includes the following regular expression. As a result, the configuration of the supplied web server does not need to be adapted.
If the preconfigured |
$-- Redirect to proxy --$
<!-- CMS-REGEX-PATTERN-START -->
regex-match="[^"'(]*?\/on\/demandware\.static\/"
$CMS_IF(#global.is("WEBEDIT"))$
regex-value="/fs5webedit_$CMS_VALUE(#global.project.id)$/proxy/on/demandware.static/"
$CMS_ELSE$
regex-value="/fs5preview_$CMS_VALUE(#global.project.id)$/proxy/on/demandware.static/"
$CMS_END_IF$
<!-- CMS-REGEX-PATTERN-END -->
Troubleshooting
ContentConnect supports developers when analyzing problems and errors in the preview, such as erroneous substitutions or poor response times while generating a preview.
Developers can add special parameters to the URL of a preview page in order to influence how the Preview Filter works and receive useful information as a result. The available URL extensions are /debugTimings=true
and /debugCCFilter=true
.
/debugTimings=true
instructs the Preview Filter to write the execution times of its processing steps as a comment at the end of the HTML document. For this purpose, the Preview Filter measures the duration of the following actions:
-
Search for content to be substituted
-
Substitution of slots with the current editorial content
-
Execution of particular substitutions via specific regular expressions
-
Complete processing of the page
If this parameter is specified, the Preview Filter generates the following output for the homepage of the reference project:
<!--
*** TIMING STATS ***
LANGUAGE-DROPDOWN = 0ms
<script [^<]*?/dwux-init.js.*?</script> = 0ms
[^"'(]*/s/SiteGenesisGlobal_MF_SP/[^"')]* = 53ms
Scanning for content replacement blocks = 1ms
CUSTOM-NAVIGATION-LEFT = 0ms
[^"'(]*?/on/demandware.static/ = 113ms
(<!-- dw.+?-->) = 1ms
<iframe.*?id="DW-SFToolkit">.*?</iframe> = 1ms
LANGUAGE-DROPDOWN-MOBILE = 0ms
<a.*?sid="([^"]*?)" = 1ms
</head> = 0ms
WILL-IGNORE-FOR-PREVIEW = 0ms
HOME-CATEGORIES = 0ms
href=("|').*.home[?] = 1ms
<!-- Demandware Analytics(([sS]*)</script>) = 1ms
<!-- Demandware Active Data (([sS]*)</script>) = 0ms
HOME-MAIN = 0ms
HOME-CC-OVERRIDE = 0ms
Total time = 172ms
-->
In addition, the Preview Filter logs some information in the FirstSpirit Server log if the /debugTimings=true
parameter is specified.
/debugCCFilter=true
means that the Preview Filter does not download the storefront, perform substitutions or present the result in the preview. The page actually generated by FirstSpirit is shown in the preview instead. The HTML therefore contains the substitution comments and specifications in addition to the editorial content. If this parameter is specified, the Preview Filter therefore generates the following output (in a shortened form) for the homepage of the reference project:
<!-- CMS-HOME-MAIN-START -->
[...]
<!-- CMS-HOME-MAIN-END -->
<!-- CMS-HOME-CATEGORIES-START -->
[...]
<!-- CMS-HOME-CATEGORIES-END -->
[...]
<!-- CMS-REGEX-PATTERN-START -->
regex-match="href=("|').*.home[?]"
regex-value="href="/fs5webedit_90169/s=qgkM/preview/90169/site/EN_GB/current/90172/90361""
<!-- CMS-REGEX-PATTERN-END -->
[...]
Using these functions requires a preview page to be called up. The address of the preview page must have one of the parameters presented here added to it. There are various ways of doing this:
-
Via the iFrame address in the ContentCreator
-
Via the address of a page in the external preview
-
Via generated links in the FirstSpirit preview, as shown here using the example of links on the homepage:
<!-- CMS-REGEX-PATTERN-START -->
regex-match="href=("|').*.home[?]"
regex-value="href="$CMS_REF(pageref:"homepage")$/debugCCFilter=true""
<!-- CMS-REGEX-PATTERN-END -->
Due to their functions, the |
5.2. Generation
In order to deploy editorial content, FirstSpirit generates two XML files, which contain content assets and slot configurations, and are transferred to the Commerce Cloud. The corresponding generation and deployment schedule has already been described. This description also explains that templates in their presentation channels populate XML collectors with content (content assets) and slot configurations. These collectors are initialized in the project settings. All content and configurations to be deployed must be written to the XML collectors. Otherwise, they will not be transferred.
One asset and one slot configuration are typically generated for each section, allowing for personalization at the section level. Content pages are the only exception. In this case, a total of precisely one content asset and one slot configuration are created.
This chapter explains how the content and configurations of the project are collected and the XML files generated.
5.2.1. Content Assets
Populating the XML collector for content assets involves the following steps:
Generating a content asset ID using a project-wide convention
In the reference project, the ID of a content asset is comprised of a project-wide prefix, the ID of the generated page reference, and the section ID. These components are separated from one another by means of a hyphen and any underscores are substituted with hyphens.
In case of a content page the content asset ID simply consists of the prefix and the ID of the generated page reference. |
$CMS_SET(set_xml_id, ps_dwAssetIdPrefix + "-" + #global.node.uid + "-" + #global.section.id)$
$CMS_SET(set_xml_id, set_xml_id.replaceAll("_","-"))$
Creating a new content asset in the XML collector
Once the ID has been determined, a new content asset is created in the XML collector using the useOrCreateContentNode
method. This asset must be populated with the content of all generated languages during the full generation. For this reason, useOrCreateContentNode
only generates a new asset if no asset with the specified ID already exists. All subsequent method calls on the XML collector then operate on this asset.
$CMS_SET(void, ps_xmlCollector.useOrCreateContentNode(set_xml_id))$
When a new content asset is created, the fsGenerationTime
custom attribute is automatically added along with the current time stamp of the generation. This is necessary to ensure that the content cleanup only deletes obsolete content assets from the Commerce Cloud after deployment.
The value of this attribute must not be changed manually following this. |
Determining the locale
Some of the following actions require a locale to be specified for the Commerce Cloud. For this purpose, the language_mapping format template maps a FirstSpirit language onto a locale of this kind, and is therefore included in each page. In the template, two variables are generated in the context of the page: set_previewLang
and set_xml_lang
. The first of these is used for generating the preview and has the format <language_COUNTRY>
. An example of a potential value is fr_FR
. The Homepage chapter also describes this aspect of the template in greater detail.
The set_xml_lang
variable is used during the process of populating the content assets. Its value for the master language is x-default
. In all other cases, it assumes the value of set_previewLang
, but substitutes the underscore with a hyphen.
Since both variables are set in the context of the generated page, they are available in all sections of the page and can therefore be used both for generating the preview and for populating the XML collectors.
Setting the display-name property
For each language, the display name of the generated page reference corresponds to the display name of the associated content asset, which is set during generation by means of the addContentAttribute
method. The set_xml_lang
variable described above is required for this.
$CMS_SET(void, ps_xmlCollector.addContentAttribute({
"name":"display-name",
"value":#global.node.getDisplayName(#global.language).toString(),
"attributes":{
"xml:lang":set_xml_lang
}
}))$
Setting the searchable-flag property to true
The content asset needs to be included in the search index of the Commerce Cloud, which is why the searchable-flag
attribute is set to true
.
$CMS_SET(void, ps_xmlCollector.addContentAttribute({
"name":"searchable-flag",
"value":"true"
}))$
Setting the online-flag property to true
The asset also needs to be available in the shop, which is why the online-flag
attribute is also set to true
.
$CMS_SET(void, ps_xmlCollector.addContentAttribute({
"name":"online-flag",
"value":"true"
}))$
Setting the body property
The editorial content from FirstSpirit is saved in the body
custom attribute. The set_xml_body
variable is first created in the reference project, and the rendered content is then stored in this variable. The variable is then transferred to the XML collector. The collector automatically embeds the content in a CDATA section, which means that no special preparation is required. Since the content is language-dependent, the locale in set_xml_lang
is used in this step too.
$CMS_SET(void, ps_xmlCollector.addCustomAttribute({
"id":"body",
"cdata":set_xml_body.toString(),
"attributes":{
"xml:lang":set_xml_lang
}
}))$
Folder
The Commerce Cloud makes it possible to specify a library folder in which it is to store a content asset. For this purpose, the XML collector provides the addFolderAttribute
method, which receives the ID of this kind of folder. In the reference project, the folder containing all the content assets for a page is stored in the form for the page itself. Each page template transfers the value of the corresponding form field to the set_parent_id
variable. The sections then use this variable to generate their assets.
$CMS_SET(void, ps_xmlCollector.addFolderAttribute({
"id":set_parent_id
}))$
Folders that are referenced in this way must be identified to the Commerce Cloud by means of corresponding nodes in the generated XML file. This allows the Commerce Cloud to create any missing folders. The XML template takes responsibility for this task, and generates a defined set of folders.
Unless any additional measures are taken, only the IDs of these folders can be reliably used in the reference project when generating content assets. This is because FirstSpirit is only able to guarantee that precisely these folders exist. In the reference project, the corresponding form elements are therefore hidden in the page templates and assigned fallback values. |
5.2.2. Slot configurations
The XML collector for slot configurations is populated in the Slot Configuration link template. Therefore, both pages as well as sections output the corresponding form elements directly via $CMS_VALUE$
calls:
$CMS_IF(!st_slotConfig.isEmpty)$
$CMS_FOR(_slotConfig,st_slotConfig)$
$CMS_VALUE(_slotConfig)$
$CMS_END_FOR$
$CMS_END_IF$
The XML for slot configurations is manually assembled in the Slot Configuration template and written to the appropriate collector using the addXml
method:
$CMS_SET(void, ps_xmlCollectorContentSlot.addXml(null, set_slotConfig.toString(), null))$
As with the process of creating the content asset, the fsGenerationTime
custom attribute is automatically added to a slot configuration along with the current time stamp of the generation. This is necessary to ensure that the content cleanup only deletes obsolete slot configurations from the Commerce Cloud after the deployment.
The value of this attribute must not be changed manually following this. |
5.2.3. Generating the XML files
Both generated XML files are based on the XML page template, which reads out the collected content and slot configurations from the XML collectors. For this purpose, the deployment schedule performs three generations:
-
A full generation for populating the XML collectors,
-
a partial generation for writing the content assets to an XML file, and
-
a partial generation for writing the slot configurations to an XML file.
The full generation must be completed before FirstSpirit can generate the XML files, which is why this step cancels the generation of the XML template. This is done using the dwre_xmlGeneration
schedule variable, which has the value false
in the full generation and the value true
in both partial generations.
Since both files are based on the same template, a feature is necessary in order to determine which XML collector is read out. This feature is the ps_importType
form field, which can assume the content_library
and content_slot
values.
In the case of content_library
, a defined set of library folders is first written to the XML collector for content assets. The getXml
method is then executed on this collector and the result - an XML document - is output via a $CMS_VALUE$
call. If ps_importType
has the value content_slot
, getXml
is called up on the collector for slot configurations instead and the result is also output.
The ContentConnect Technical Pages
content folder contains two pages that are based on the XML template: Shop Assets
, for which ps_importType
has the value content_library
, and Shop Slot Configurations
, for which this form field is set to content_slot
. These pages form the basis of the Shop Assets
and Shop Slot Configurations
page references in the ContentConnect Export Files
structure folder; a partial generation is executed for each of these page references.
5.3. Navigation
The storefront’s main navigation function can be used in FirstSpirit to navigate both the shop and the content maintained on the FirstSpirit side. Custom entries can also be added.
5.3.1. Main navigation
The main menu is primarily used to navigate between the various category pages within the preview (see figure Navigation). The main menu is part of the HTML downloaded during the preview from the Commerce Cloud Storefront and is therefore predefined by Commerce Cloud.