Taking Notez – Island Pond Consulting

Business users of IBM WebSphere Portal version 8.5 can offer customers better digital experiences by using Vanity URLs. Managing this new feature should not introduce any new headaches for administrators but a few tips and a little prior planning will go a long way toward ensuring a smooth implementation.

URLs are important; short, readable URLs empower potential customers and users to locate meaningful resources quickly. In contrast, typical portal URLs are cumbersome.  Vanity URLs, new to IBM WebSphere Portal 8.5 offer features with greater possibilities than portal URL Mappings without incurring direct administrative effort.

Requirements and Base Knowledge

In order to work with VanityURLs the portal platform must have Managed Pages support enabled. This is the default (and recommended) configuration of a new IBM WebSphere 8.5 installation. If the portal was migrated from an earlier version, support for Managed Pages must be enabled. A ConfigEngine task, enable-managed-pages must be executed in order to proceed. In addition to enabling support for Managed Pages, sites that are migrate will also require manual enablement of Vanity URLs. This ConfigEngine task, enable-vanityurl-support, creates a new custom property in the WP Configuration Service resource environment provider and sets the property named vanityurl.support.enabled to “true”. Information regarding this task may be found in the Knowledge Center at: http://www-01.ibm.com/support/knowledgecenter/#!/SSHRKX_8.5.0/mp/wcm/van_url_cfgtsk_enable_vus.dita

Information and additional details for the enablement of Managed Pages task can be found in the IBM Knowledge Center at: http://www-01.ibm.com/support/knowledgecenter/#!/SSHRKX_8.5.0/mp/migrate/mig_t_enable_mngpages.dita

In addition to platform readiness, administrators seeking to manage Vanity URLs will need to be familiar with the WebSphere Application Server Integrated Solutions Console (ISC), the ISC trace string settings interface, Web Content Manager Syndication, Site Authoring Toolbar, portal Release configuration database, the JCR (Java Content Repository) database, HTTP server rewrite rules, Friendly URL paths, and URL Mappings.

Creating Vanity URLs

Business users employ the Site Authoring Toolbar to create and manage portal pages, set content preferences, and to create or modify Vanity URLs. A nice PDF describing the design objectives and features of the toolbar is available at IBM’s web site. When creating or modifying a Vanity URL the toolbar is loaded in the current page context. This means that the state of the page, including selected content, default content, locale, and authentication stipulations are available at the time the definition of a Vanity URL is being set or modified.

A Vanity URL is stored as a property of the Managed Page site area artifact created in the Portal Site WCM library. In addition to specifying (1) a name, users may specify a (2) locale and (3) indicate a choice for web content associated with a Web Content Viewer portlet. It is worth noting, as indicate in this following screen shot, that a page may have multiple Vanity URLs such that each may have unique locale and content settings. In addition, users can indicate whether a request to the Vanity URL will force authentication.

Three aspects of Vanity URL creation.

When a Vanity URL is created a reference, for performance purposes, is also created in the portal Release configuration database. The URL syntax, which can be previewed in the page properties editor of the toolbar, is http://host/wps/vanityurl/<customurl&gt;.

Enhancing Vanity URLs

A simple url, such as host://wps/vanityurl/Specials is probably adequate for many needs but most business users will wish to simply even this URL. Many will prefer a syntax such as http://host/Specials.  This is one of several enhancements that are supported. This shortened syntax will require administrative effort consisting of modifications to the configuration of the external http server.

If, for example, you are using the IBM HTTP Server an administrator will modify the web server’s configuration file. This file, httpd.conf, can be modified to enable rewrite rules. Then, once the rewrite engine is enabled, the administrator will provide a rule to parse any incoming “single path” requests and redirect the request to the vanity url servlet. The IBM Knowledge Center provides detailed instructions on the process here.

The rewrite module, once enabled, will need at least one rule. The following rule redirects “all single path requests to the vanity URL servlet. The P flag at the end of the line tells the rewrite engine to use a proxy request. This flag is required for the IBM WebSphere® Application Server plug-in to handle the request without an additional redirect.”

RewriteRule	^/([^/]+)$             /wps/vanityurl/$1        [P]

Other rules will be required to support projects, static files, and the Web Application Bridge. Please refer to the link referenced above for the necessary details.

Not only might users wish to enhance their Vanity URLs by shortening them for customers they may also wish to preview them in the same manner. To do so, execute the ConfigEngine task “enable-vanityurl-httpserver-preview”. Later, if you wish to return to the default full vanity url syntax you can execute the “disable-vanityurl-httpserver-preview” task. Complete documentation for this process is found here in the Knowledge Center.

A final enhancement administrators should consider is provision of a custom URI for handling missing vanity urls. By default, when a customer requests a resource for which a vanity url no longer exists or was never defined, a 404 error is returned. Administrators may, alternatively define a value for an additional custom property of the WP  Configuration Service resource environment provider. To do this a ConfigEngine task is needed that includes the object identifier of the URI to which errors will be redirected:

./ConfigEngine.sh set-vanityurl-error-uri 
                  -DPortalAdminPwd=password -DWasPassword=password
                  -DErrorURI=cm:oid:ibm.portal.Home    

Vanity URLs, Life Cycle, and Release Management

One area in which administrators coming to versions 8 or 8.5 are likely to struggle is release management. This is because Managed Pages has a significant impact on how artifacts are managed. The advent of Managed Pages raises the role of WCM syndication to a new level making it a significant player in the task of achieving a consistent state between staging and production.

Because Vanity URLs are primarily members of site area properties in the Portal Site library with corresponding pages and labels in the portal configuration Release database it is easy to forget or overlook the necessity to syndicate the web content libraries in order to propagate Vanity URLs. This may be exacerbated when the decision to populate the target system during the first release by using a clone of the JCR. (Cloning is a popular strategy used to avoid lengthy data transfers associated with large web content libraries.) This approach mandates execution of another ConfigEngine task, “sync-vanityurl-data”. This synchronizes the configuration database with the JCR so that the Vanity URL references are set in the release database. Full instructions are available in the Knowledge Center here.

Troubleshooting

Even under the best of circumstances trouble may arise. Typical errors are those associated with missing or non existent Vanity URLs. When this happens the vanity url servlet will return a 404 error.

To more completely understand the problem you may need to apply a diagnostic trace. Use the value “com.ibm.wps.portlet.vanityurl.*=all” and provide the trace log to IBM for assistance. Information about this string and related errors is available here.

One other item, though not explicitly related to troubleshooting, is the relationship of vanity urls to search and indexing.  Administrators should be aware that vanity urls are not included in seed lists.  To ensure successful index ranking, be certain to define friendly urls for all pages whether or not vanity urls are used.

Conclusion

IBM WebSphere Portal version 8.5 offers customers better digital experiences through Vanity URLs. With the tips and practices described in this article, administrators are better equipped to ensure a smooth implementation.