Connector for HCL Commerce Manual / Version 2107
Table Of Contents
The CoreMedia Fragment Connector is the component that connects with
CoreMedia CAE in order to integrate CoreMedia content fragments in
store pages. In order to perform a fragment request, the
LiveContextEnvironment has to be configured in the
WCDE_installdir/workspace/Stores/WebContent/WEBINF/web.xml configuration
file, as described below.
Changing the web.xml file
There are different approaches to configure the loading mechanism for properties for the
fragment connector. The LiveContextEnvironment can load its configuration
directly from web.xml, from a properties file and from the STORECONF
table. The default implementation is
PropertiesBasedIBMLiveContextEnvironmentFactory.
The PropertiesBasedIBMLiveContextEnvironmentFactory extends the
IBMLiveContextEnvironmentFactory and in addition loads properties from a resource
file on the classpath. If the resource file cannot be found - or the resource cannot be loaded,
it will throw RuntimeExceptions. The location of the properties resource must be given in a
servlet context parameter named livecontext.properties.location In the first place
this factory tries to get a parameter from STORECONF table, in the second place
from the properties file and if not found as fallback from web.xml.
Other approaches are the following:
The
DefaultLiveContextEnvironmentFactoryreads the connector properties directly as context parameters directly from theweb.xml.The
IBMLiveContextEnvironmentFactoryextends theDefaultLiveContextEnvironmentFactoryand can be configured via theSTORECONFtable. If properties are not available in theSTORECONFtable the factory reads directly from theweb.xmlconfiguration.
The fragment connector is the central component in the commerce-led integration scenario (see Chapter 8, Commerce-led Integration Scenario). Configure the fragment connector for example as follows:
Add the
LiveContextEnvironmentconfiguration as shown inWCDE-INSTALL/workspace/Stores/WebContent/WEB-INF/web.xmlto the corresponding file in the HCL RAD workspace.In the file
WCDE-INSTALL/workspace/Stores/WebContent/WEB-INF/coremedia-connector.propertiesconfigure at least the parametercom.coremedia.fragmentConnector.liveCaeHostwith the host URL of your Content Application Engine (CAE). If you use a single commerce system that should be able to connect to both, preview and production CAE, you also need to setcom.coremedia.fragmentConnector.previewCaeHostwith the host URL of the preview CAE. In case you have a dedicated Staging commerce system with separate Production System, you only need to configure one CAE host, each. Find the meaning of all parameters in the list below.
com.coremedia.fragmentConnector.cookieDomainThe
cookieDomainis used when a fragment request is created. All accessible cookies are copied and added to this request using the specified cookie domain. This way it is ensured that the CAE session cookie is detected by the CAE and fragments can be rendered depending on the logged on user. ThecookieDomaincan contain multiple cookieDomains separated by comma.com.coremedia.fragmentConnector.unconditionalCookieNamesA fragment request promotes cookies from the commerce request to the CAE. However, this policy is overruled by other features (for example, the
newPreviewSessionURL parameter). In theunconditionalCookieNamesproperty you can specify cookies that are always to be passed with the fragment request. The value must be a comma separated list of cookie names.com.coremedia.fragmentConnector.environmentThe optional parameter is used to identify the HCL Commerce system that is requesting a fragment from a CAE. It may be used to serve different sites for each commerce system that is connected to a single CMS. The strategy for resolving this parameter is implemented in the class
LiveContextSiteResolver. The methodfindSiteFor(@NonNull FragmentParameters fragmentParameters)checks if theenvironmentparameters has been passed as request matrix parameter. If set (for example:site:Aurora), a lookup is made if a site with a matching name and locale exists. If no site is found with the given name, the default lookup strategy, implemented infindSiteFor(@NonNull String storeId, @NonNull Locale locale)is used.com.coremedia.fragmentConnector.liveCaeHostThe
liveCaeHostidentifies the Live CAE, to be precise, the Varnish, Apache or any other proxy in front of the Live CAE. Each request made by the fragment connector will be prefixed with theurlPrefix.com.coremedia.fragmentConnector.previewCaeHostThe
previewCaeHostidentifies the Preview CAE, to be precise, the Varnish, Apache or any other proxy in front of the Preview CAE. Each request made by the fragment connector will be prefixed with theurlPrefix. ThepreviewCaeHostis only required if you want a single HCL Commerce instance being able to access the preview CAE in case of HCL Commerce system preview and the live CAE in all other cases. Additionally, the preview mode can be invoked through an HTTP header. If you have a dedicated commerce instance for staging and separate production commerce system, you do not need to set this property. If this parameter is not set, the parameterliveCaeHostwill be used instead.com.coremedia.fragmentConnector.urlPrefixThis prefix identifies the web application, the servlet context and the fragment handler to handle fragment requests. The default request mapping of all the handlers within CoreMedia Blueprint that are able to handle fragment requests start with
service/fragment.com.coremedia.widget.templatesConfigures the template lookup path that is used when rendering CoreMedia Widget includes. Default is
/Widgets-CoreMedia/com.coremedia.commerce.store.widgets.CoreMediaContentWidget/impl/templates/com.coremedia.fragmentConnector.defaultLocaleEvery fragment request needs to contain the tuple
(storeId, locale)because it is needed to map a request to the correct site. UsingdefaultLocaleyou can set a default that is used for every request that does not contain a custom locale. You will see how it is used later, when you see theIncludeTagin action.com.coremedia.fragmentConnector.contextProvidersCSVEvery fragment request can be enriched with shop context specific data. It will be most likely user session related info, that is available in the HCL Commerce and can be provided to the backend CAE via a
ContextProviderimplementation. See Section 8.3, “Extending the Shop Context” for details.com.coremedia.fragmentConnector.isDevelopmentThe fragment connector will return error messages that occur in the CAE while rendering a fragment if the
isDevelopmentparameter is set to true. For production environments you should set this option tofalse. Errors are logged than but do not appear on the commerce page so that the end user will not recognize the errors.com.coremedia.fragmentConnector.disabledTurn this flag to true if you want to disable the fragment connector. Disabled means that the fragment connector always delivers an empty fragment. This property is not mandatory. If this property is not set, the default is false.
com.coremedia.fragmentConnector.connectionTimeoutThe connection timeout in milliseconds used by the fragment connector; that is the time to establish a connection. A value of "0" means "infinite". Default is "10000".
com.coremedia.fragmentConnector.socketTimeoutThe socket read timeout in milliseconds used by the fragment connector; that is the time to wait for a response after a connection has successfully been established. A value of "0" means "infinite". Default is "30000".
com.coremedia.fragmentConnector.connectionPoolSizeMaximum number of connections used by the fragment connector. Default is 200.
com.coremedia.fragmentConnector.previewCaeAccessTokenHeaderAn optional access token that is sent along with all HTTP requests towards the CoreMedia preview CAE. Can be used by the CAE to authorize the access.
com.coremedia.fragmentConnector.liveCaeAccessTokenHeaderAn optional access token that is sent along with all HTTP requests towards the CoreMedia live CAE. Can be used by the CAE to authorize the access
com.coremedia.fragmentConnector.isPrefetchEnabledIf set to true the connector tries to prefetch fragments for the current commerce page
