29 Configuring Vanity URLs
Vanity URLs do not replace the existing URLs in the product. They exist alongside of the existing URLs, as either can be used to access the content. A vanity URL can be auto-generated and custom created by a content contributor in the Oracle WebCenter Sites: Contributor interface.
An example of a "normal" WebCenter Sites URL could be:
http://www.example.com/<context>/Satellite?c=Page&cid=3451344545&pagename=avisports/Page/HomeLayout
where the vanity URL for the same asset could be
http://www.example.com/Running/Home
This shows how the vanity URL is useful, being both simpler to type (particularly on a Mobile device), and easier for a user to read and recall later.
Vanity URLs consist of two parts. First, the WebRoot, which is the control of how the vanity URL is interpreted in different environments. The other part of a vanity URL is the URL Pattern or Free Form entry. The URL Pattern is a rule defined for an entire asset type, while the Free Form entry is created individually by the content contributor for each asset.
This chapter includes the following sections:
29.1 Generating Vanity URLs
Vanity URLs can be constructed in two ways. One way a vanity URL can be constructed manually, in a one-off manner by Content Contributors (see Working with Vanity URLs in Using Oracle WebCenter Sites). The other method generates a vanity URL from a pattern, and is described in this section.
Topics:
29.1.1 Configuring Auto-Generated URLs
Vanity URLs based on patterns are automatically generated for individual assets. After a pattern is registered, the vanity URL is generated when the asset is saved for the first time. Patterns can be created for every asset type; however, these patterns are only valid for a single site. The same pattern must be created for each site that shares the asset type.
While creating vanity URLs for assets, users edit the default vanity URLs of the assets and Oracle WebCenter Sites allows the creation of duplicate vanity URLs. Therefore, the auto generated URLs are changed to user generated URLs and users can decide if they want to delete the URLs, redirect them to another URL, and so on.
Note:
Changes to patterns are only processed when an asset is created or saved. If you modify a pattern or create a new one it only applies to assets created after the pattern is saved.
To configure an auto-generated vanity URL:
- In the General Admin tree, expand the Admin node, expand the Asset Types node, expand the node for the specific asset type you are creating an auto-generated URL for. Under the specific asset type node, expand URL Pattern, and then double-click Add New.
The URL Pattern Form opens.
Figure 29-2 URL Pattern Form - Blob (Detail)
Description of "Figure 29-2 URL Pattern Form - Blob (Detail)"
29.1.2 Working with WebRoots
The WebRoot is used to control how the vanity URL is interpreted. WebRoots are like assets. After it is configured, a WebRoot must be published to the destinations for it to work in delivery system.
WebRoots come in two forms: absolute and relative. An absolute WebRoot must contain the entire URL prefix (including host and port information), it may also optionally contain a PATH prefix, it is unique to every server. A relative WebRoot contains only information related to the PATH and does not contain any information on the host or port. Both URLs are handled identically by WebCenter Sites; however, with relative WebRoot only a single WebRoot is required across multiple environments, for instance development, staging, and production environments. With absolute WebRoot each of these environments will have unique WebRoot.
To eliminate this limitation, the concept of VirtualRoot is supported. Using VirtualRoot requires setting an environment identifier (sites.environment) in the wcs_properties.json file to identify that they are valid for the given environment; if the parameter is missing then the WebRoot is used. It is important to determine and understand the types of WebRoots as you can have reason to have both absolute and relative roots defined at the same time.
Table 29-1 lists the advantages and disadvantages of these types of WebRoots.
Table 29-1 Advantages and Disadvantages of WebRoot Types
| WebRoot Type | Advantages | Disadvantages |
|---|---|---|
|
Absolute WebRoot |
|
|
|
Relative WebRoot |
|
|
|
Combination |
|
|
29.1.2.1 Different Types of WebRoots Required For a URL: Examples
The following examples use the same vanity URL used in the introduction — http://www.example.com/Running/Home — and illustrate using and accessing it from management and production servers.
The following vanity URLs are used for each environment:
-
Production:
http://www.example.com/Running/Home -
Management:
http://management.example.com/Running/Home
The server name used for the production server is http://www.example.com/ and the server name used for the management server is http://management.example.com/.
For an absolute WebRoot, a unique WebRoot for each environment is required, with the root URL as http://www.example.com. In the Property Management Tool, set the sites.environment property to management. The site is avisports.
It is important to note that the value specified in WebRoot for the virtual root URI and the value specified in the sites.environment property must be the same.
For a relative WebRoot, a single Web Root is used all environments. The root URL is /. The site is avisports.
29.1.2.2 Creating a New WebRoot
To create a new WebRoot:
- From the Admin tab, expand the WebRoots node. Double-click Add New.
The WebRoot edit form opens as shown in Figure 29-3 but with all fields blank.
After the WebRoot is created for the first time, it is available as an asset type in the Admin tab under the Asset Type node.
29.1.2.4 Editing an Existing WebRoot
To edit an existing WebRoot:
- Click the Edit icon to edit the WebRoot.
The WebRoot Edit form opens.
29.1.3 Working with URL Patterns
Automatic patterns are the heart of vanity URLs. However, an administrator pattern matched URL will likely make up the bulk of the vanity URLs present on a site. Patterns take their form from a combination of paths and variables, where the variables are either fields from the asset or predefined functions.
Note:
All the parts of URL are URL encoded before the save.
The actual variables that are present will differ based on the asset type selected, but all asset types share some common variables. The following table lists the most common variables.
Table 29-2 Common Asset Type Variables
| Variable Name | Variable Type |
|---|---|
|
createdby |
string |
|
createddate |
date |
|
description |
string |
|
enddate |
date |
|
fwtags |
array |
|
id |
long |
|
locale |
string |
|
name |
string |
|
startdate |
date |
|
status |
string |
|
subtype |
string |
|
template |
string |
|
updatedby |
string |
|
updateddate |
date |
Click a variable to place it after the pattern field. It does not make a difference where the cursor is located, the new pattern is always the last item.
Variables are specified by ${<Name>}. For example, to call the ID of an asset, use ${id}.
Variables of types string, int, and long can be used directly, without modification.
Variables of type array have to be specified such that only a single value is extracted. For example, to get the first tag defined for an asset, use ${fwtags[0]}, or use the function listAsPath. Array numbering begins with 0 and using a value outside of bounds of the array will result in "null."
Variables of type date have to be formatted; a function formatDate is provided for this.
Other types, such as url, may not be usable or may require a function to generate a URL. Use the Evaluate URL Pattern option to assist you with these variables.
Variables are defined using Java standard types so that normal Java functions can also be added. For example, on the string variable "name," name.toLowerCase() converts the name to lower case.
This section covers the following topics:
29.1.3.1 Using Functions
Functions are useful in converting and formatting data to include in the vanity URL. There are predefined functions in WebCenter Sites that are useful in creating vanity URLs.
29.1.3.2 Using Patterns
The examples are based off the avisports Article asset type. The asset name is "Baker Likely to Stay With Stars."
Note:
The first part of the URL is always the WebRoot. This is the local system name and context root in the example. The next part, Avi, is the filter prefix. Only the unique path is provided in these examples.
Given the asset "Baker Likely to Stay With Stars," there are several options available to generate a URL. Each example shows the function and the resulting URL.
| Steps | Function | Resultant URL |
|---|---|---|
| Start with a simple name pattern. | /Article/${name} |
/Article/Baker+Likely+to+Stay+With+Stars |
| Convert the name to lower case. | /Article/${name.toLowerCase()} |
/Article/baker+likely+to+stay+with+stars |
| Remove the spaces from this URL | /Article/${f:spaceToUnderscore(name)} |
/Article/Baker_Likely_to_Stay_With_Stars |
| Use multiple variables | /Article/${id}/${createdby} |
/Article/1328196049037/fwadmin |
| Use a function within a function | /Article/${(f:formatDate(createddate,"yy/MM/dd")} |
/Article/12-04-27 |
29.1.4 Disabling Redirection to Vanity URLs
There are some instances where the developer will want vanity URLs to be temporarily disabled. For example, a developer might want a testing instance that does not redirect to the vanity URL. You can disable redirection to vanity URLs in WebCenter Sites by setting a JVM parameter.
Set the -Dsites.disablevanityurl option as a JVM parameter in Java options on the application server.
JAVA_OPTIONS=$JAVA_OPTIONS -Dsites.disablevanityurl="true"
29.2 Using Vanity URL with System Tools
Using the System Tools node, an administrator can view all presently defined vanity URLs and resolve URL conflicts as the following sections describe:
29.2.1 Viewing All Vanity URLs
To view all vanity URLs:
Because every URL defined (for all sites) are present on this list, it is necessary to filter it using the search box provided to locate URL(s) of interest. From this menu you can manually delete a vanity URL, or inspect if it is a problem or confirm where a conflict is originating. However, if the URL is based upon a pattern then it is automatically regenerated when the asset is next saved.
29.2.2 Resolving Vanity URL Conflicts
Vanity URLs are unique in that there cannot be multiple vanity URLs with the same path (even across WebCenter Sites). For example, if there are two sites and each site has a Rule pattern /Page/${name} and if the sites use the same name for a page (for instance, "Home"), then a conflict will occur.
Whichever page is saved first will succeed and create a vanity URL, but, the second page will fail to create a vanity URL.
- When this occurs, use the System Tool to locate what is blocking the creation of the Vanity URL and, if required, remove the existing URL to allow the new one to be created.
- This issue can be mitigated by ensuring that the WebRoot is unique to a single site.
29.3 Resolving Vanity URLs Using a Rewriter Filter
There are two ways to resolve a vanity URL. The first is by using a web server and rewriting the URL. The second way is designed for instances where a web server is not present such as often in development, and relies upon a filter.
WebCenter Sites contains a URL rewriter filter that is used, by default, only for sample sites. This rewriter filter can be configured to be used along with a WebRoot for any site. The filter will intercept any call through it (based upon a string match it begins with) and pass the call through to WebCenter Sites as a vanity URL filter.
In simple terms, it allows vanity URLs to operate without a rewriting rule on the web server. The major limitation of using this filter is that it must have the context root and a unique prefix to ensure that the proper URLs are treated as vanity URLs.
Note:
"FSII" and "Avi" are the parameters pre-configured for URL rewrite filter in the web.xml when sample sites are installed.
To enable the rewriter filter:
For example:
Assume a relative WebRoot of /Avi and a path of /Running/Home, the resulting URL using the filter would look like:
http://<Sites Host>:<Sites Port>/<Context Root>/Avi/Running/Home
Because a filter is used, the use of a prefix (specifically Avi in this example) is required both in the filter and in the WebRoot.
Note:
Vanity URLs support query parameters. Required parameters have been removed from vanity URLs, though sometimes additional data must be passed as part of the URL. In such cases the existing parameters are concatenated onto the existing URL. For instance, passing in time=true the URL above sent to sites would look like:
http://<Sites Host>:<Sites Port>/<Context root>/Avi/Running/Home?time=true
29.4 Using Vanity URLs for Mobile Sites
In most cases, those using a mobile-specific site will want to use a different URL for mobile users. Not only will mobile users benefit from a shorter URL, but there is often a separate domain and different URLs. To set up a different domain and different URL for the mobile pages of a website, complete these items:
- WebRoot must be set for the Mobile domain names. The Root URL of the WebRoot should have mobile domain names.
- Choose the right host names when creating vanity URLs for mobile device groups. This ensures that the links are correctly generated for the mobile domain names.
- All other steps including Web Server URL Rewrite are the same as mentioned in Working with WebRoots, Generating Vanity URLs, and Using Vanity URL with System Tools.
29.5 Using the Web Server with Vanity URLs
Using a web server with URL rewriting allows access to vanity URLs in a similar way to the filter, and you also have all the control and power that URL rewriting entails.
When using a web server, all rewritten vanity URLs must be split into two sections before sending them to WebCenter Sites. One is the WebRoot, the other is the path. For example, use the WebRoot http://www.example.com and a pattern that generates /Running/Home for the URL http://www.example.com/Running/Home. To pass this URL from a web server we must break up the URL into the WebRoot and path. These are then passed separately as query parameters to a special filter in WebCenter Sites. The vanity URL filter used to handle rewritten URLs is named "Sites" and is accessed by <content root>/Sites.
The two parts of the URL are broken up into lookuphost, and lookuppage. The lookuphost refers to the WebRoot (full server name, port and prefix if absolute WebRoot, or only the prefix if relative WebRoot). The lookuppage refers to the remainder of the PATH after the prefix. Using the above URL as an example, the URL passed to WebCenter Sites would have to be rewritten to look like:
http://<Sites Host>:<Sites Port>/<contextpath/Sites?lookuppage=/Running/Home &lookuphost=http://www.example.com
Note:
Vanity URLs support query parameters. Required parameters have been removed from vanity URLs, though sometimes additional data must be passed as part of the URL. In such cases the existing parameters are concatenated onto the existing URL. For instance, passing in time=true the URL above sent to sites would look like:
http://<Sites Host>:<Sites Port>/<Context root>/Avi/Running/Home?time=true
29.6 Using mod_rewrite with Vanity URLs
Every web server and site are unique, so the following should be viewed as guidelines and examples as to how to use mod_rewrite (which is used in OHS, Apache and IBM HTTP Server to rewrite URLs). Your system will likely require modifications to the rules to operate correctly.
There are two methods to use mod_rewrite. It can be used to directly transform the URL for the WebCenter Sites filter, or it can be used in conjunction with the URL rewriter filter to perform the same action in a way that will allow for much simpler mod_rewrite rules. Examples of both methods are provided. To determine which is right for you, decide if the extra step (and hence cost) of having the WebCenter Sites filter break apart the vanity URLs is worth the simplified rewrite rules.
All subsequent steps are based off manually compiled Apache 2.4.x. If using a version shipped with an operating system, the changes required to enable and configure mod_rewrite may differ, but the rules and concepts will not.
This section covers the following topics:
29.6.1 Setting Up mod_rewrite
To set up mod_rewrite:
Note:
There are web pages that allow for much easier construction and testing. It is suggested that you use one of these sites when initially writing up the mod_rewrite rules.
29.6.1.1 Setup for Provided Examples
To provide some examples of mod_rewrite rules, first define what the environment looks like. Below is a sample based on the vanity URLs used in this guide. You should use the same elements changing out the values for your environment to start.
The vanity URLs a customer is expected to see:
-
Production:
http://www.example.com/Page/Surfing http://www.example.com/Article/Baker_Likely_to_Stay_With_Stars http://www.example.com/Home http://www.example.com/Home?time=true
-
Development:
http://dev.example.com:8080/Running/Home
Generic WebCenter Sites information:
-
Production context root:
/cs -
Production rewrite filter:
/AVISPORTS -
Development context root:
/csdev -
Development rewrite filter:
/Avi
Web Roots Defined for each Server:
-
Production - absolute:
http://www.example.com/ -
Development - relative:
/Avi
The following table provides the URL structure:
| URL | WebRoot | Path | Query Psarameters |
|---|---|---|---|
http://www.example.com/Page/Surfing |
http://www.example.com |
/Page/Surfing |
|
http://www.example.com/Article/Baker_Likely_to_Stay_With_Stars |
http://www.example.com |
/Article/Baker_Likely_to_Stay_With_Stars |
|
http://www.example.com/Home |
http://www.example.com |
/Home |
|
http://www.example.com/Home?time=true |
http://www.example.com |
/Home |
time=true |
http://dev.example.com:8080/Running/Home |
/Avi |
/Running/Home |
There are two filters. The first is the WebCenter Sites vanity URL filter, the second is the WebCenter Sites rewrite filter. When using the rewrite filter it passes the data to the vanity URL filter transparently.
When using the WebCenter Sites vanity URL filter, the URLs are expected in this manner:
-
Production:
-
http://www.example.com/Page/Surfinglookuphost=http://www.example.com &lookuppage=/Page/Surfing
-
http://www.example.com/Article/Baker_Likely_to_Stay_With_Starslookuphost=http://www.example.com &lookuppage=/Article/Baker_Likely_to_Stay_With_Stars
-
http://www.example.com/Homelookuphost=http://www.example.com &lookuppage=/Home
-
http://www.example.com/Home?time=truelookuphost=http://www.example.com &lookuppage=/Home&time=true
-
-
Development:
-
http://dev.example.com:8080/Running/Homelookuphost=/cs/Avi&lookuppage=/Running/Home
-
When using the WebCenter Sites rewriter filter, the URLs are expected in this manner:
-
Production:
-
http://www.example.com/Page/Surfing/cs/AVISPORTS/Page/Surfing
-
http://www.example.com/Article/Baker_Likely_to_Stay_With_Stars/cs/AVISPORTS/Article/Baker_Likely_to_Stay_With_Stars
-
http://www.example.com/Home/cs/AVISPORTS/Home
-
http://www.example.com/Home?time=true/cs/AVISPORTS/Home?time=true
-
-
Development:
-
http://dev.example.com:8080/Running/Home/csdev/Avi/Running/Home
-
29.6.2 About Converting with mod_rewrite
After choosing some URLs and breaking them down to component parts, it is now necessary to convert these URLs using mod_rewrite. The rules for mod_rewrite consist of two parts: the first is a regular expression which matches the URL provided to the web server, and the second is how it will appear when passed on. If the first part fails to match, then the URL is passed on to the next rewrite rule; if no defined rule matches, then the URL is passed on unchanged. Thus the order of the rules become important if more than a single rule is present.
Note:
1. mod_rewrite is an optional component that you have previously enabled. If you create a mod_rewrite rule without actually enabling the mod_rewrite component, then the rule is skipped. There are no errors and nothing is rewritten. For this reason it is suggested to ensure debugging is active during development and monitor the error.log for details related to mod_rewrite.
What is discussed in this section only covers a very small portion of what mod_rewrite can handle and for most sites a more complex rule is likely to be required. For more information, see the vendor's documentation.
This example uses the first URL for production:
http://www.example.com/Page/Surfing
Create this rule for it:
RewriteRule ^(.*)$ /<context>/Sites?lookuphost=http://www.example.com&lookuppage=$1 [L]
This rule has four component parts which are described in the following table:
RewriteRule — |
^(.*)$ |
/<context>/Sites?lookuphost=http://www.example.com&lookuppage=$1 |
[L] |
|---|---|---|---|
It is a statement that the following entry is a mod_rewrite rule). |
It is a regular expression, which breaks down as follows:
This expression then indicates that between the start and end of string save all text to a variable. |
It is the WebCenter Sites context root, filter, and path for vanity URL, which breaks down further as follows:
|
It informs mod_rewrite that this is the end of the rules. All mod_rewrite rules must end with this. |
29.6.3 Using the WebCenter Sites Filter with mod_rewrite
The following rule handles /Page/Surfing, but it also handles any other page sent in, extracting everything after the host to the end of the line.
RewriteRule ^(.*)$ /<context>/Sites?lookuphost=http://www.example.com& lookuppage=$1 [L]
So the rule also handles:
http://www.example.com/Article/Baker_Likely_to_Stay_With_Starsand
http://www.example.com/Home
However, this rule does not handle the following URl because it has a query parameter being passed in along with the host and path:
http://www.example.com/Home?time=true
29.6.4 Using the Rewriter Filter with mod_rewrite
When using the rewrite filter, URLs do not have to be broken down the way they are for the vanity URL filter. Instead, the Sites Context Root and rewriter Filter Prefix are added to the URL (This is very similar to using WebCenter Sites before the introduction of vanity URLs, so it is likely that modify existing rules can be easily modified to support vanity URLs.
http://www.example.com/Page/Surfing as the URL, which expects /<context>/AVISPORTS/Page/Surfing:29.6.5 Using Static Content with mod_rewrite
An issue with using mod_rewrite and vanity URLs is accessing existing CSS and static images. Often these are stored either on the application server or on the web server in a directory named after the site. Often the rewrite rules will result in making them inaccessible.
29.7 Customizing Vanity URLs
WebCenter Sites allows you to customize auto-generated vanity URLs, so that you can dynamically set them.
-
CustomElements/VanityUrl/sitename/assettype/ModifyWebrefs -
CustomElements/VanityUrl/assettype/ModifyWebrefs -
CustomElements/VanityUrl/sitename/ModifyWebrefs -
CustomElements/VanityUrl/ModifyWebrefs
Where sitename is the name of the site where the user is logged in and assettype is the type of the asset that is being saved.
Note:
Only one element according to precedence is executed.Table 29-3 describes the two objects that are available in the element scope: assetData and webrefs.
Table 29-3 Description of assetData and webrefs
| Object | Description |
|---|---|
|
assetData |
An instance of AssetData containing current data of the asset. |
|
webrefs |
List of instance of WebReference. It contains list of auto-generated webreferences for the current asset. It also acts as a return object. All the webreferences given by this object will be assigned to the asset. |
29.7.1 Creating a Customized Vanity URL
The following example explains how to create a customized vanity URL.
- Create an URL pattern as shown in the following figure. For detailed steps, see Generating Vanity URLs.
An attempt will be made to create a static URL for the asset.
- Create a new element ‘
CustomElements/VanityUrl/avisports/AVIArticle/ModifyWebrefs’. For this example, we have created a groovy element using Sites Explorer as shown in the following figure.Figure 29-9 Create a Groovy Element Using Sites Explorer
Description of "Figure 29-9 Create a Groovy Element Using Sites Explorer"
