Store configuration files

Customization and configuration of the store requires modification, or addition and extension of configuration files in the custom stores web archive (crs-web.war) on the Store server. The following sections detail the specific files, their locations, and their functions for customization of the store. In addition, the configuration file on the Transaction Server required to be modified for the Store server is also detailed.

File locations

The following table describes the location of essential files within the Store server, and where they need be placed to override their originals in the extended stores web archive. Ensure that you replicate the full hierarchical file structure, and append the -ext naming convention to customized files.

Note: The WebSphere Commerce enterprise archive (WC.ear) is not on the Store server. A crs.ear enterprise archive, which is the store archive, is available on the Store server. The WC.ear archive is the enterprise archive for the Transaction Server.

Original directory	Extension directory
crs-web.war/	crs-web.war/
crs.ear/	crs-web.war/

Store server configuration files

WebSphere Commerce enterprise archive (WC.ear)

• workspace_dir/WC/xml/config/com.ibm.commerce.foundation/wc-component.xml

  The WebSphere Commerce foundation component configuration file on the Transaction Server. For store, this configuration includes variables required for storefront cache invalidation, store preview, and for the rendering of email templates (JavaServer Page files).

  <_config:configgrouping name="RemoteStoreConfiguration">
  <!-- value to remote store web host name -->
  <_config:property name="wc.store.remote.webHostName" value="host_name"/>
  <!-- value to remote store web host HTTP port number -->
  <_config:property name="wc.store.remote.webNonSSLPort" value="port"/>
  <!-- value to remote store web host HTTPS port number -->
  <_config:property name="wc.store.remote.webSSLPort" value="port"/>
  <!-- value to remote store context root -->
  <_config:property name="wc.store.remote.webContextPath" value="store_context_path"/>
  <!-- value to remote store preview context root -->
  <_config:property name="wc.store.remote.previewContextPath" value="preview_context_path"/>
  

  Where:

  host_name

  The host name of the store web server. Used for email template rendering and store preview.

  port

  The port number for the store web server. Used for email template rendering and store preview.

  • The default non-SSL port number is 8080.

  • The default SSL port number is 8443.

  store_context_path

  The non-preview context path for store pages. Used for email template rendering. We can determine the default context path by viewing the contents of the wc-store.xml configuration file in your Externalized Customization workspace. This file is in the crs\xml\config directory. Within the file, locate the InstanceProperties/Websphere/WebModule element. The default context path for store pages is defined within the Module that has the name property with a value Stores. The default context path for store pages is /webapp/remote/stores.

  preview_context_path

  The store preview context path for store pages. Used for store preview rendering. We can determine the default context path by viewing the contents of the wc-store.xml configuration file in your Externalized Customization workspace. This file is in the crs\xml\config directory. Within the file, locate the InstanceProperties/Websphere/WebModule element. The default store preview context path is within the Module that has the name property with a value Preview. The default preview context path is /webapp/remote/preview.

Store server enterprise archive (crs.ear)

• crs.ear/xml/config/wc-store.xmlThe following sections in this file are customizable:

  • <config/InstanceProperties/WebSphere/WebModule>

  • <config/InstanceProperties/Instance>

  • <config/InstanceProperties/Instance@enableDialogActivity>

  • <config/InstanceProperties/WhiteListProtection>

  • <config/InstanceProperties/XSiteScriptingProtection>

  • <config/Components>

  • <config/NonEncryptedParameters>

  • <config/SEOConfiguration>

  • <config/DoubleClieckMonitoredCommands>

  Note: enableDialogMarketing is the only customizable configuration option that is unique to IBM Commerce on Cloud. This feature is disabled by default. When enabled, marketing events are triggered through the web channel. This feature enables the marketing system on the Transaction Server to evaluate user behavior based on marketing rules.

  For more information about these customizable sections and values, see Store server configuration file (wc-store.xml).

stores web archive

• crs-web.war/crs/xml/mapper/SEOUrlMapper.xml

  The SEO URL mapper format configuration. This file is not directly customizable. To change the SEO URL mapper format configuration, change the config/SEOConfiguration value within wc-store.xml. For more information about constructing SEO-friendly URLs, see Constructing SEO-friendly URLs by using pattern files in the WebSphere Commerce Version 9 documentation.

• crs-web.war/WEB-INF/AliasConfig.xml

  The alias configuration used by the alias tag and alias bean tag.

stores web archive

• crs-web.war/WEB-INF/xml/config/bi/biConfig.xml

  The Coremetrics integration configuration. Can be modified directly. For details about the biConfig.xml file and how to update it, see Updating the biConfig.xml file in the WebSphere Commerce Version 9 documentation.

• crs-web.war/crs/xml/config/wc-attribute-masking.xml

  The masking configuration for logging. Can be modified directly. For more information about masking in logging, see Logging and tracing in the WebSphere Commerce Version 9 documentation.

• crs-web.war/WEB-INF/xml/seo/stores/storeDir/SEOURLPatterns.xmlThe SEO URL pattern configurations. Can be modified directly. For more information about constructing SEO-friendly URLs, see Constructing SEO-friendly URLs by using pattern files in the WebSphere Commerce Version 9 documentation.

  Note: Previous SEOURLPatterns-ext.xml files can still be used to customize the SEO URL patterns. However, the default SEOURLPatterns.xml file is not updated automatically during a migration. This file must be migrated from new releases manually.

REST template

REST templates define request formats for the REST services that are executed by Spring controllers on the Store server. Each action controller calls REST services as defined in REST templates for executing business logic. REST services that are defined in REST templates are grouped by resource definitions, and each resource definition is subdivided into method definitions:

• A resource is characterized by a path which is a URI prefix that is common to a group of REST services.

• Each method definition is characterized by the remaining path after the resource path in the full URI of a REST service.

Each resource or method has a name. A resource name and a method name can uniquely identify a REST service. For each method definition, a template is defined for composing a REST request from the parameters of a web request. For each Spring action controller, the resource name and method name of the REST service to be executed by this controller is defined by a property of the definition of this controller in the Spring configuration XML file.

• crs-web.war/WEB-INF/xml/config/componentDir/rest-template-config.xml

  These files contain the REST template configuration for each component.

  The contents of these files appear as such:

  <resource path="{serverHost}/{contextPath}/store/{storeId}/loginidentity" name="loginIdentityHandler">
  <serverParam name="serverHost">$WCParam.serverHost</serverParam>
  <serverParam name="storeId">$WCParam.storeId</serverParam>
  …
  <method name="logonAndChangePassword" httpMethod="POST" path="">
  <template>
  <![CDATA[{"logonId" :
        "$logonId","logonPassword" :
        "$logonPasswordOld","logonPasswordNew" :
        "$logonPassword","logonPasswordVerify"
        : "$logonPasswordVerify"}]]>
  </template>
  </method>
  …
  </resource>

  Where:

  resource

  The REST resource.

  path

  The REST resource URL. The variable in this URL is dynamically changed. Therefore, it must be enclosed within the curly brackets ('{}'), and its value is defined by the following serverParam entries.

  name

  The defined resource name of the service.

  serverParam

  This element is a subelement within the resource tag.

  The variables used in the resource path. The serverHost, contextPath and storeId variables are automatically resolved to be the values for the backend WebSphere Commerce server based on the current request scheme and preview mode. Other parameters are obtained from the current request parameters.

  method

  This element is a subelement within the resource tag.

  The method definition.

  name

  The defined method name. Together with the resource name it becomes the parameter property that is defined in the action controller definition. For example, for this service example, the parameter is loginIdentityHandler.logonAndChangePassword.

  httpMethod

  The HTTP method for this REST request.

  path

  The method part of the REST resource in the URL. For example, the method path for the service /store/{storeId}/person/@self is @self. If this parameter is left empty, then the resource path URL used is the full URL.

  template

  The input values required by the REST request in JSON format. For POST, PUT, and DELETE services, the body JSON is in this template format. For GET services, the variables in the template are appended in the URL as request parameters. The variable values are found from request properties using the values in the templates without the dollar sign as the request property name. If a variable value does not have the dollar sign, the variable value in the template is the value composed to the REST request.

Note: You do not need to configure the REST response format for the REST template. The response format is configured by the Transaction server.

Spring configuration files

• crs-web.war/WEB-INF/spring/storeDir/controllers.xml imports all other controller definition files.

• crs-web.war/WEB-INF/spring/storeDir/views.xml imports all other view definition files.

Important:

• It is a recommended best practice that you modify these files by using the -ext naming convention, and to use store identifiers in the controller and view entries.

• The Spring entries in controllers.xml and views.xml outside of the individual store folders apply to all stores. If these files are modified directly, then delta configurations are added to the store folders of new stores that are published later. The delta configurations are used because the modified non-ext files are not compatible with the default provided starter store. If you customize your new store to be compatible with your modified global configurations, we can remove these configuration files.

Related concepts
Store assets
Spring MVC and store controller customization

Related tasks
Customizing the store
Customizing the store Spring MVC configuration
Adding or modifying REST templates