ContentConnect

ContentConnect allows editors to:

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.

FirstSpirit and Commerce Cloud are linked by an architecture made up of a range of components (see figure Architecture). These components are:

Figure 1. Architecture

The individual components always interact in accordance with the following schema:

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.

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.

Figure 2. Page Rendering

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.

Figure 3. Languages

This information is presented in more detail in the Generation and Homepage chapters.

The ContentConnect module has the following technical requirements:

This section contains information that should be noted when using the 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 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.

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.

The delivery includes three cartridges: int_espirit_core, int_espirit_sfra and int_espirit_sitegenesis.

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 B2C Commerce Development → Development Components → Cartridges.

Next, the int_espirit_core cartridge must be added to all sites that are to receive FirstSpirit content, as well as the business manager site. You can find relevant instructions in the Commerce Cloud documentation under B2C Commerce Development → Getting Started for Developers → Register Your 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_sitegenesis.

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,in which the firstSpiritImportSchedule.xml file is stored.

A job ID must first be defined within the file before the import. This ID ensures the uniqueness of the jobs for the different sites and must be specified as a value for the job-id attribute of the job tag. It is recommended to include the ID of the respective site in the corresponding job ID.

The job schedule configured in the file consists of two job flows. Both have the context tag with the site-id attribute, the value of which must be configured accordingly. In addition, they contain the two job steps ImportContent and ImportContentSlots. These define different parameters whose default values can be kept mostly. Only the WorkingFolder and FileNamePattern parameters need to be adapted to the specific project:

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 customAttributesMetadata.xml export file must be imported. It is stored in the zip file importExamples.zip within the metadata directory, which is included in the delivery.

For this, the following steps must be performed in Salesforce Business Manager:

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 B2C Commerce Development → 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.

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 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.

In addition when using content cleanup:

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.

In addition when using content cleanup:

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:

The templates from the int_espirit_sfra cartridge are used to add new slots to the site. The delivery provides the export file slotConfigurations.xml to be imported with slot configurations for these slots. It is stored in the zip file importExamples.zip within the metadata directory, which is included in the delivery.

The ContentConnect delivery contains three modules that must be added to the FirstSpirit server. To install the modules, open the ServerManager and select Server properties → Modules.

Figure 4. Module management in the server properties

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.

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.

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 firstspirit5 → conf directory of your FirstSpirit server and add the following lines to the file firstspirit5 → conf → fs-wrapper.conf.

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

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 firstspirit5 → conf → fs-wrapper.conf.

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

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 Project → Import 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).

Figure 5. Imported project in the ServerManager

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 Project properties → Project components. 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).

Figure 6. Configuration dialog for the project component

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 Project properties → Web components.

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):

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.

Figure 8. Web components in the project properties

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.

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.

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.

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.

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.

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.

Example

An example web.xml in which two parameters are configured could look as follows:

Example web.xml. 

<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>

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.

Specifying the 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 Project properties → Resolutions area and specified in the corresponding areas in the sections.

Figure 9. Resolutions

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.

Figure 10. Generation schedule actions

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:

Figure 11. Schedule action

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 Default URLs is therefore selected, which is absolutely essential at this point.

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.

Figure 12. Content preparation action

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.

Figure 13. Partial generation

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:

Figure 14. 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. Additionally, the prefix must be the same as the Prefix for absolute paths used in the full generation.

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 → Creating Roles and Assigning Permissions 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. The mediaurl always has the following structure:

https://<SUBDOMAIN INSTANCE>.demandware.net/on/demandware.servlet/webdav/Sites/Libraries/<SITE ID|LIBRARY ID>/default/<PREFIX>

The mediaurl must refer to an existing directory. Furthermore, as with the url, the prefix must be the same as the Prefix for absolute paths used in the full generation.

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 or false. If true is set, all the files and directories under the specified URL will be deleted before the transfer starts. If the parameter is set to false or no value at all, all the existing files and directories under the specified URL will be retained. New data will either be added or, in the case of existing data, overwritten.

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:

Figure 15. Schedule action

The action loads a configuration dialog, in which two parameters must be defined in addition to a freely assignable name.

Figure 16. Schedule action parameters

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 Salesforce Commerce Cloud Importer requires a successful WebDAV deployment, this too must not be executed in the event of an error.

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:

Figure 17. Schedule action

In addition to a freely assignable name for this schedule action, the associated configuration dialog contains the following parameters:

Figure 18. Schedule action 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.

Content asset cleanup → Enabled

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.

Slot configuration cleanup → Enabled

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 Salesforce Commerce Cloud Cleanup must be the last action of the schedule. For the same reason, content cleanup requires that this action only performs full generations. Furthermore, replication within the Commerce Cloud is not recommended during the execution of the cleanup.

Since the Salesforce Commerce Cloud Cleanup requires a successful execution of the job schedules and thus the import of the content, it must not be executed in the event of an error.

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 Project properties → ContentCreator area within the ServerManager. In the reference project ContentConnect Reference Project, this setting has already been applied (see figure Element Status Provider).

Figure 19. Element Status Provider

In addition, in the Project properties → Options 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.

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 Extras → Change permissions 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.

You can find more detailed information in the BasicWorkflows Documentation.

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.

Figure 20. Project settings

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.

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.

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:

Syntax. 

<!-- 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:

Format template. 

$-- 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 -->

ContentConnect Preview Language

The following pattern is needed to configure the display language in the ContentCreator:

Pattern. 

$-- 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.

Proxy integration. 

$-- 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)$/s=****/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:

If this parameter is specified, the Preview Filter generates the following output for the homepage of the reference project:

Output of the Preview Filter for the homepage with /debugTimings=true. 

<!--
*** TIMING STATS ***

LANGUAGE-DROPDOWN = 0ms
&lt;script [^&lt;]*?/dwux-init.js.*?&lt;/script&gt; = 0ms
[^&quot;'(]*/s/SiteGenesisGlobal_MF_SP/[^&quot;')]* = 53ms
Scanning for content replacement blocks = 1ms
CUSTOM-NAVIGATION-LEFT = 0ms
[^&quot;'(]*?/on/demandware.static/ = 113ms
(&lt;!-- dw.+?--&gt;) = 1ms
&lt;iframe.*?id=&quot;DW-SFToolkit&quot;&gt;.*?&lt;/iframe&gt; = 1ms
LANGUAGE-DROPDOWN-MOBILE = 0ms
&lt;a.*?sid=&quot;([^&quot;]*?)&quot; = 1ms
&lt;/head&gt; = 0ms
WILL-IGNORE-FOR-PREVIEW = 0ms
HOME-CATEGORIES = 0ms
href=(&quot;|').*.home[?] = 1ms
&lt;!-- Demandware Analytics(([sS]*)&lt;/script&gt;) = 1ms
&lt;!-- Demandware Active Data (([sS]*)&lt;/script&gt;) = 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:

Output of the Preview Filter for the homepage with /debugCCFilter=true. 

<!-- 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:

<!-- CMS-REGEX-PATTERN-START -->
    regex-match="href=("|').*.home[?]"
    regex-value="href="$CMS_REF(pageref:"homepage")$/debugCCFilter=true""
<!-- CMS-REGEX-PATTERN-END -->

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.

$CMS_SET(set_xml_id, ps_dwAssetIdPrefix + "-" + #global.node.uid + "-" + #global.section.id)$
$CMS_SET(set_xml_id, set_xml_id.replaceAll("_","-"))$

$CMS_SET(void, ps_xmlCollector.useOrCreateContentNode(set_xml_id))$

$CMS_SET(void, ps_xmlCollector.addContentAttribute({
    "name":"display-name",
    "value":#global.node.getDisplayName(#global.language).toString(),
    "attributes":{
        "xml:lang":set_xml_lang
    }
}))$

$CMS_SET(void, ps_xmlCollector.addContentAttribute({
    "name":"searchable-flag",
    "value":"true"
}))$

$CMS_SET(void, ps_xmlCollector.addContentAttribute({
    "name":"online-flag",
    "value":"true"
}))$

$CMS_SET(void, ps_xmlCollector.addCustomAttribute({
    "id":"body",
    "cdata":set_xml_body.toString(),
    "attributes":{
        "xml:lang":set_xml_lang
    }
}))$

$CMS_SET(void, ps_xmlCollector.addFolderAttribute({
    "id":set_parent_id
}))$

$CMS_IF(!st_slotConfig.isEmpty)$
    $CMS_FOR(_slotConfig,st_slotConfig)$
        $CMS_VALUE(_slotConfig)$
    $CMS_END_FOR$
$CMS_END_IF$

$CMS_SET(void, ps_xmlCollectorContentSlot.addXml(null, set_slotConfig.toString(), null))$

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.