IBM WCM pre-rendering best practices

Introduction

This article outlines best-practices and patterns for IBM Lotus Workplace Web Content Management (WCM) pre-rendering based on first-hand experiences from successful projects using Agile software development methodologies.

WCM pre-rendering is used to create static HTML content from WCM libraries served through highly-performant and scalable web server farms that do not require the dynamic content delivery capabilities of the WCM “Connect” Servlet. The WCM CacherModule is used to pre-render a site or content item and can be configured to run automatically at pre-defined times in addition to being a process that can be manually invoked by a user.

The following topics are covered in this article:

1. Limitations of WCM pre-rendering
2. WebSphere Portal deployment patterns
3. WebSphere Portal configuration for WCM pre-rendering
4. Output modalities
5. Manually pre-rendering a library/site
6. Manually pre-rendering a content item
7. Security context for pre-rendering
8. Content transfer to HTTP servers
9. WCM pre-render performance tuning
10. Frequently Asked Questions
11. Conclusions

All configuration and examples shown are based on an installed version of IBM WebSphere Portal 6.0.1.5.

Limitations of WCM pre-rendering

To begin with, it is important to understand the limitations of WCM pre-rendering:

• Sites, site areas, and content items can only contain characters that are valid in file names for the operating system on which you are pre-rendering.
• The path to the content item (inclusive of the directory path where files are pre-rendered to) cannot exceed a length of 255 characters in Windows or 1024 characters on Unix.
• JSP components cannot be pre-rendered.
• Pre-rendered content will contain the portal context root URL (i.e. /wps/wcm/connect) in all page and resource links. From an SEO perspective this URL prefix is non-optimal therefore the use of a mod-rewrite filter to remove these characters is recommended.
• Personalization elements can only be pre-rendered if the personalization rule is configured for anonymous access.
• The page navigation component cannot be used in a pre-rendered site.

WebSphere Portal deployment patterns

There are two main deployment patterns available for WebSphere Portal server when using WCM pre-rendering:

1. Centralised authoring and pre-rendering of WCM content from the same WebSphere Portal server
2. Distributed authoring of WCM content and syndication to a single WebSphere Portal server for pre-rendering

Centralised authoring and pre-rendering

This pattern for pre-rendering of WCM content is the simplest deployment pattern and should be used for low-volume sites that have infrequent content updates. Content authoring and pre-rendering occur on the same server at different times of the day.

Advantages

• Less infrastructure provisioning
• Lower software licensing costs
• No syndication overhead
• Simplification of server management

Disadvantages

• Limited fail-over capabilities
• Higher load (although not necessarily concurrent) on the Portal server due to single-site authoring and pre-rendering
• Limited demarcation from work-in-progress content to published content
• Potential for “locking” of libraries during the pre-rendering process

Distributed authoring and syndication to a single pre-rendering server

This pattern for pre-rendering of WCM content requires more planning for WebSphere Portal deployments. It should be used in scenarios where there is a higher volume of content, and a large WCM user-base performing frequent content updates against multiple disparate libraries. Content creators work on different authoring servers on different libraries where-after syndication transfers content to the pre-rendering server.

Advantages

• Distribution of authoring and therefore server processing load
• Clear demarcation of work-in-progress draft content from published content
• Greater resilience against peak server loads during business hours

Disadvantages

• Higher costs due to extended infrastructure provisioning and software licensing
• Overhead of managing and monitoring syndicator/subscriber server-pairs
• Managing the process of synchronized library publishing to a web site

It is strongly recommended that if multiple WebSphere Portal servers are to be provisioned in a pre-rendering deployment topology that they reside within the same LDAP domain. Failure to do this will result in the need to run the WCM member-fixer as a post-syndication activity in order to re-map Portal user IDs bound to the WebSphere Member Manager.

WebSphere Portal configuration for WCM pre-rendering

WCM pre-rendering must be enabled by editing WCMConfigService.properties located in [portal_server_root]/wcm/shared/app/config/wcmservices

Ensure that the following lines exist:

connect.moduleconfig.cacher.cacherclass=com.aptrix.cacher.Cacher
connect.businesslogic.module.cacher.class=com.aptrix.cacher.CacherModule
connect.businesslogic.module.cacher.remoteaccess=true
connect.businesslogic.module.cacher.autoload=true

If the value for connect.businesslogic.module.cacher.remoteaccess is false it will not be possible for a user to run a manual pre-render unless they are logged into the server and have launched a browser on the host of WebSphere Portal Server WCM instance. If security is a concern then minimize the likelihood that a user will invoke a manual pre-render remotely by setting this value to false.

In the table below, substitute appropriate values where required. For example, the values for directories; start times; and sites should be specific to your installation and functional requirements. Due to table formatting limitations, some of the properties and values contain additional spaces.

Property	Value	Description
deployment.subscriberOnly	true	Disables processes that are not required for a subscriber only server.
connect.moduleconfig. cacher.destdir	C:\wcm-cacher\ pre-render-output	Base directory under which each site cache will be created. There will be one subdirectory created for each site.
connect.moduleconfig. cacher.tempdir	C:\wcm-cacher\ pre-render-temp	The temporary directory that is required to build the site cache prior to moving the data over to the base directory specified by the connect.moduleconfig. cacher.destdir property.
connect.moduleconfig. cacher.overwritecache	false	true The pre-renderer will overwrite files in the destdir cache directory (then delete unneeded files). This results in a progressive change in site content as seen by the user. false The pre-renderer renames the tempdir to the destdir to achieve an instant update to a new version of the pre-rendered site.
connect.moduleconfig. cacher.delay	1	This is used to set the time, in seconds, between requesting a page while caching.
connect.moduleconfig. cacher.busydelay	5	This is used to set the time, in seconds, of the busy delay setting. This is used if executing within the busy start to busy end period. Otherwise the delay setting is used.
connect.moduleconfig. cacher.busystart	9:00 am	Enter an absolute time as shown. These would align with when “business hours” start for the geographic location of the server.
connect.moduleconfig. cacher.busyend	5:00 pm	Enter an absolute time as shown. These would align with when “business hours” end for the geographic location of the server.
connect.moduleconfig. cacher.overwritecache	false	The pre-renderer will overwrite files in the destdir cache directory (then delete unneeded files). This results in a progressive change in site content as seen by the user.
connect.moduleconfig. cacher.rendereruser	Anonymous	This determines the user to be used to render the Web Content Management content. Either type Anonymous or Administrator or a specific Member Manager user or group name. The site is pre-rendered based on this user’s security rights. If the user specified here does not have access to a particular component it will not be pre-rendered.
connect.moduleconfig. cacher.task.cacherurl	http://${WCM_HOST}: ${WCM_PORT}/ ${WCM_CONTEXT_ROOT} /connect	The full URL to the CacherModule, which performs the pre-rendering.
connect.moduleconfig. cacher.task.servletpath	/connect	The path to the Web Content Management servlet not including the context path.
connect.moduleconfig. cacher.defaultcontentname	index.html	This sets the name of the default or home file of the site used when accessing the pre-rendered site.
connect.moduleconfig. cacher.task.sites	shared/resources,europe/content,asia/content	The sites within a Web Content Management environment to cache are entered here, separated by commas.
connect.moduleconfig. cacher.task. interval.recurrence	Not applicable.	This value should be commented out.
connect.moduleconfig. cacher.task. interval.startdelay	Not applicable.	This value should be commented out.
connect.moduleconfig. cacher.task. scheduled.times	6:00 am, 8:00 pm	This value should be commented out.
connect.businesslogic. module	[somevalue1],[somevalue2],[etc],cacher	Ensure that the business logic setting includes the cacher module in the comma separated list of values.

After making configuration changes for pre-rendering, restart the WebSphere Portal server.

Output modalities

If the value for connect.moduleconfig.cacher.overwritecache is true then pre-rendered content will bypass the connect.moduleconfig.cacher.tempdir and be written directly to the connect.moduleconfig.cacher.destdir location.

It is recommended that the server which hosts the WebSphere Portal WCM instance is separate from the web servers responsible for content delivery. At the conclusion of a successful pre-render, files should be copied from the directory specified in connect.moduleconfig.cacher.destdir to the web server. On that basis the suggested approach is to specify a value of false for the property connect.moduleconfig.cacher.overwritecache and perform a verification step to ensure valid content was pre-rendered and is ready for transfer to the web server.

The sequence diagram illustrating manual invocation of a library/site pre-render for content delivered through a public-facing web site has the following steps:

1. An administrator logs into the Portal Server
2. The administrator manually invokes a pre-render for a specific library/site combination
3. The WebSphere Portal Server starts the pre-render process (site cacher) writing pre-rendered output to the temporary directory
4. Once the pre-render process has completed the pre-rendered content is copied to the destination directory
5. The administrator copies the pre-rendered content in the destination directory to a directory used by the HTTP server
6. HTTP server delivers content to users

Manually pre-rendering a library/site

Pre-rendering can be manually invoked for a library by using a browser to launch the WCM CacherModule. When pre-rendering a site, the library name and site name must be specified with a URL structure similar to the following:
http://host_name:port_number/wps/wcm/connect?MOD=Cacher&SRV=cacheSite&Site=site_name&library=library_name

Manually pre-rendering a content item

Pre-rendering can be manually invoked for a content item by using a browser to launch the WCM CacherModule. If the content item is default content for a site area, pre-render the site area itself. For example:
http://host_name:port_number/wps/wcm/connect/library_name/site_name/site_area_name?MOD=Cacher

If the content item is not default content for a site area then specify it using the value in content item name field. For example:
http://host_name:port_number/wps/wcm/connect/library_name/site_name/site_area_name/content_name?MOD=Cacher

Manually pre-rendering a content item will result in it being directly written to the location specified for connect.moduleconfig.cacher.destdir irrespective of whether the value for connect.moduleconfig.cacher.overwritecache is true or false.

Security context for pre-rendering

It is recommended that the pre-rendering process is run using the lowest security privileges required, the Anonymous user. This user does not require an account however it is essential that anonymous portal user permissions are granted to every facet of the library and site that are to be pre-rendered. Amongst other things, this includes the library, site, site areas, content items, workflows, workflow stages, library components, menus, navigators, authoring templates and presentation templates.

A simple test to determine whether or not a content item will pre-render correctly using an anonymous context is to browse to the content item on the pre-rendering server and confirm that it renders as expected when previewed using the fully-qualified URL to the content. In other words, you should be able to view the item from a browser that does not have a valid portal session without having to authenticate at the WCM login page.

Content transfer to HTTP servers

Before transferring content to a web server ensure that pre-rendering of a library/site combination has completed successfully using either of the following approaches:

Search the Portal SystemOut.log file for the most recent occurrence of a message relating to the library/site combination that was pre-rendered. The following message [sic] indicates that the pre-render has completed for the library shared and the site resources:

[25/07/10 11:53:54:375 EST] 00000088 AbstractCache I   IWKPL1017X: Finished extracing site: shared\resources

Alternatively, confirm that the contents of the directory specified in connect.moduleconfig.cacher.destdir exist for the library/site combination that was pre-rendered. For example, the directory connect.moduleconfig.cacher.destdir/shared/resources should contain the static content for the library shared and the site resources.

On the web server create a directory that maps appropriately to the structure specified in the URLs for pre-rendered content. There should be no broken links or missing styles when browsing content.

WCM pre-render performance tuning

1. Ensure that the value of deployment.subscriberOnly is set to true. This disables the item gatherer module used by a syndicating server.
2. Set the value for connect.moduleconfig.cacher.delay to 0 (seconds) so that there is no delay between caching pages outside business hours.
3. Set the value for connect.moduleconfig.cacher.busydelay to 1 (seconds) so that there is a balance between the subscriber task process and cacher module during business hours.
4. Schedule automated pre-rendering to execute outside the hours specified for connect.moduleconfig.cacher.busystart and connect.moduleconfig.cacher.busyend
5. Ensure there are no errors relating to EJPSG0002E: Requested Member does not exist in SystemOut.log during the pre-render process. If these are being encountered, run the member fixer on the authoring WebSphere Portal Server to remap user IDs.

Frequently asked questions

Q – What happens if a pre-render is running and someone attempts to manually start it for the same library/site combination?
A – The command is ignored and will not be queued. From the log files a message similar to the following will be displayed:

IWKPL1040X: Cacher is currently active for the site [shared/resources]

Q – Why are changes that I made to a content item not showing up on the pre-rendered page?
A – It may be related to a caching issue. Run the pre-rendering again using the additional parameter SRV=flushPageCache. For example:
http://host_name:port_number/wps/wcm/connect/library_name/site_name/site_area_name/content_name?MOD=Cacher?SRV=flushPageCache

Q – Does the use of pre-rendering change the content authoring process?
A – No. Pre-rendering imposes no change to the content authoring process.

Q – Why is my site not pre-rendered to disk?
A – It may be related to a configuration issue in any of the variables listed in WCMConfigService.properties. Validate there are no errors in the log files and that directory permissions have been configured appropriately for the account which runs the WebSphere Portal Server process.

Q – Is there a pub/sub mechanism where clients can register to receive notification that pre-rendering has finished?
A – No. Pre-rendering is run as an asynchronous background process on the WebSphere Portal Server.

Q – Can I alternate the times for which specific libraries/sites are pre-rendered automatically?
A – No. All libraries and sites specified for connect.moduleconfig.cacher.task.sites are pre-rendered when the cacher module runs at a specified time.

Q – Do all libraries specified for connect.moduleconfig.cacher.task.sites pre-render concurrently?
A – It depends. Queuing may occur depending on the number of threads running concurrently in the cacher module and the number of libraries/sites that have been specified for pre-rendering.

Q – How long does pre-rendering of a library/site combination take?
A – It depends entirely on how many content items are in the library, how much processing capacity is available on the server, and how much tuning has been performed on the WebSphere Portal server.

Conclusions

WCM Pre-rendering is used to create static HTML content from WCM libraries served through highly performant and scalable web server farms that do not require the dynamic content delivery capabilities of the WCM “Connect” Servlet.

Pre-rendering can be used on WCM libraries of varying size and can be scheduled to run automatically at specific times or be manually invoked by a user.

With pre-rendering it is possible to create a separation of concerns between a WebSphere Portal instance and the content delivery web servers used by an organisation. If dynamic functionality is required at a later date, pre-rendering can be disabled and the WebSphere Portal server can be configured to deliver content via the WCM “Connect” servlet without requiring any changes to the underlying content authoring process or usage patterns.