1. Administering Oracle WebCenter Sites
  2. Monitoring and Maintaining WebCenter Sites
  3. Configuring Vanity URLs

34 Configuring Vanity URLs

Vanity URLs are short, readable, and easily managed URLs. WebCenter Sites provides you the facility to create vanity URLs that often include the name or other descriptive information about the content on a web page to which the vanity URL points.

Vanity URLs do not replace the existing URLs in the product. They work along with the existing URLs. Users can use existing or vanity URLs to access the content. Content Contributors can auto-generate or create a vanity URL in the 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.

Other important information about managing vanity URLs are provided in the following sections:

34.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:

34.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:

  1. 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 34-1 URL Pattern Form - Asset

    Description of Figure 34-1 follows
    Description of "Figure 34-1 URL Pattern Form - Asset"

    Figure 34-2 URL Pattern Form - Blob (Detail)

    Description of Figure 34-2 follows
    Description of "Figure 34-2 URL Pattern Form - Blob (Detail)"
  2. Enter a name for the pattern in the Name field. This name is only used to reference this pattern and is unique; it can be changed at any time.

    Note:

    The following characters are not allowed in the Name field: single quote ('), double quote ("), semicolon (;), colon (:), percent (%), ampersand (&), question mark (?), less-than sign (<), greater-than sign (>), and backslash (\).

  3. In the Pattern field, enter the rule that defines the vanity URL. Lists of valid attributes and functions which can be used are displayed on the right side. See Working with URL Patterns.
  4. In the Blob Headers field (available only if a blob is selected), enter the rule used to define the blob headers in the vanity URL.
  5. The Site is the site the pattern is applied for, and only lists sites for which the asset type is enabled. The selection of the site also narrows the selections for the Host (WebRoot), Subtype, Template (asset only), and Wrapper (asset only).

    Note:

    Patterns defined will remain even if the asset type is later disabled for that site; however, the use of these URLs could result in a broken page.

  6. The Host is the WebRoot to which the vanity URL is applied. Only WebRoots that are defined for this site or "any" are displayed. The pattern does not work without a WebRoot.
  7. The Subtype is the subtype of the asset type to which the vanity URL is applied. The selection of Subtype further restricts the available items for Template and Wrapper.

    Note:

    The Subtype field for blobs do not show Any as an option for flex assets. The Subtype field for blobs do not appear for basic assets.

  8. The Field is the blob to be rendered by this URL. This field is present only when a blob is selected. There may be multiple items available if the asset contains multiple blob entries.

    Selecting the Is Downloadable checkbox has the browser display a save dialogue when the vanity URL is accessed, instead of attempting to view the blob object within the page.

  9. Device Group provides a list of defined device groups. This field is present only when an asset is selected. Device groups are formatted into lists depending on the extension and regardless of their current state within the site. For more information on device groups, see About Device Groups and Suffixes in Developing with Oracle WebCenter Sites.
  10. The Template is the template for the URL and all templates valid for the asset type, subtype and site are displayed regardless of the existence of a mobile variation. All templates that are valid are shown, however not all templates may have a variation for the specified Device Group. It is up to the administrator to ensure the proper variation exists when using a non-default device group.
  11. The Wrapper provides a list of all wrapper elements that are valid for the selected Template. If none exist then this field is disabled.
  12. At this point click Save to save the pattern and continue working, or evaluate the URL pattern.

    The Evaluate URL Pattern section of the form shows an example of what a pattern generated vanity URL will look like. It is recommended to evaluate the URL pattern before saving to validate your pattern.

    Note:

    If there is no asset of the given type then you cannot use this feature.

  13. The Asset list allows you to select an asset currently defined for the pattern type. The "look ahead" feature also works to enter an asset's name. After an asset is selected, WebCenter Sites evaluates the pattern and shows how this asset's URL will appear. This is just an example of the URL's final appearance. The URL is not valid until the pattern is saved and the asset is edited and saved.

34.1.2 Working with WebRoots

WebRoots form integral parts of vanity URLs. WebRoots are required to distinguish between vanity URLs which have the same base URL, but are used for different environments, for example production, management, administrative, and so on.

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.

The following table lists the advantages and disadvantages of these types of WebRoots.

Table 34-1 Advantages and Disadvantages of WebRoot Types

WebRoot Type Advantages Disadvantages

Absolute WebRoot

  • Full URL opens to the Content Contributor

  • A unique URL is required for every environment.

  • Virtual roots require setting a WebCenter Sites property.

  • Difficult to test vanity URLs before publishing.

Relative WebRoot

  • Single WebRoot works across all Systems

  • Vanity URLs can be easily tested before publishing

  • Content Contributors do not see the full URL, only the Path.

  • May require additional steps in rewriting the URL.

Combination

  • Full URL opens to the Content Contributor

  • Single WebRoot works across all Systems

  • Vanity URLs can be easily tested before publishing

  • More URLs are present and must be stored/published.

  • Content contributors will see both relative and absolute WebRoot URLs. Since there are more URLs it can be confusing to the Content Contributor.

34.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.

34.1.2.2 Creating a New WebRoot

To create a new WebRoot:

  1. From the General Admin tree, expand the Admin node, expand the WebRoots node, and then double-click Add New.

    The WebRoot edit form opens, as shown in the following figure, but with all fields blank.

    Figure 34-3 WebRoot Edit Form

    Description of Figure 34-3 follows
    Description of "Figure 34-3 WebRoot Edit Form"
  2. Enter a name in the Host Name field.

    This name is the unique identifier for the WebRoot instance. It can be used in render tags to get a specific vanity URL of an asset. This value cannot be changed after the WebRoot is saved.

    Note:

    The following characters are not allowed in the Name field: single quote ('), double quote ("), semicolon (;), colon (:), less-than sign (<), greater-than sign (>), percent (%), and question mark (?). Additionally, the name cannot end with a backslash (\).

  3. Enter a URL in the Root URL field.

    The value for the Root URL can be either absolute or relative. For an absolute WebRoot, typically this is the URL that is used to render the asset in delivery environment. For the relative WebRoot this would be /<Optional PATH Prefix>.

    For the Content Contributor this is the URL that is used as a prefix when displaying the defined vanity URLs. See the examples of Root URLs in the following table:

    Table 34-2 Examples of Root URLs

    Absolute Root URL... Relative Root URL...
    Using Only the Hostname Using Both the Hostname and Prefix for the Path Using the Hostname for a Mobile Site Using Using
    Production URL: http://www.example.com

    Complete vanity URL: http://www.example.com/Running/Home

    Production URL: http://www.example.com/Prefix

    Complete vanity URL: http://www.example.com/Prefix/Running/

    Production URL: http://www.example.mobi

    Complete vanity URL: http://www.example.mobi/Running/Home

    		 Production URL: /<context>/example

    Complete vanity URL: http://<Current Host Name>/<context>/example/Running/Home

    		 Production URL: /

    Complete vanity URL: http://<Current Host Name>/Running/Home
  4. Enter one or more virtual URLs. The virtual URL has two parts:

    • Environment: The identifier for the other environments. Environments must be identified by setting sites.environment=<name> in the wcs_properties.json file. Set this property from the Property Management Tool in the Admin interface. For instructions, see the Properties in the Core Category in Property Files Reference for Oracle WebCenter Sites.

    • Root URL: This is the URL that is used to render the asset in other environments such as editorial, staging, and so forth.

    When first displayed, there is only one row for adding an environment and root URL. Additional lines of Environment and Root URL fields are added by clicking the Add New button.

    The virtual URL entered must have an absolute Root URL. The following table provides fields of the virtual URL that you need to populate:

    Table 34-3 Fields of Virtual URLs

    Management URL Using Both the Hostname and Prefix for the Path Using the Hostname for a Mobile Site

    If, for example, management URL is http://management.example.com/Running/Home, populate the fields as follows:

    • Environment:management
    • Root URL:management.example.com

    • sites.environment=management in wcs_properties.json (use the Property Management Tool to set this property).

    If, for example, staging URL is http://staging.example.com/Running/Home, populate the fields as follows:

    • Environment:staging
    • Root URL:management.example.com

    • sites.environment=staging in wcs_properties.json (use the Property Management Tool to set this property).

    If, for example, development (including port) URL is http://dev.example.com:8080/Running/Home, populate the fields as follows:

    • Environment:dev
    • Root URL:dev.example.com:8080

    • sites.environment=dev in wcs_properties.json (use the Property Management Tool to set this property).

    Note:

    Virtual Root URL is not used in display in the Contributor interface. It is used only for rendering the web pages in different environments, and only when the Environment matches the value provided in the sites.environment property in wcs_properties.json.

  5. Select one or more sites. The WebRoot can be enabled for specific sites using the Sites field.

    In the proceeding examples we would set the Site to avisports, because these URLs are unique to this site.

  6. After all information is added, click the Save icon.

    The WebRoot is created.

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.

34.1.2.3 Viewing a WebRoot

To view a WebRoot:

  1. From the General Admin tree, expand the Admin node, expand the WebRoots node, and then double-click a listed WebRoot.

    The WebRoot Content form opens, showing the saved information for that WebRoot.

Figure 34-4 WebRoot Content Form

Description of Figure 34-4 follows
Description of "Figure 34-4 WebRoot Content Form"
34.1.2.4 Editing an Existing WebRoot

To edit an existing WebRoot:

  1. From the General Admin tree, expand the Admin node, expand the WebRoots node, and then double-click a listed WebRoot.

    The WebRoot Content form opens.

  2. Click the Edit icon to edit the WebRoot.

    The WebRoot Edit form opens.

    Figure 34-5 WebRoot Edit Form

    Description of Figure 34-5 follows
    Description of "Figure 34-5 WebRoot Edit Form"
  3. The stored information opens in the Host Name, Root URL, Virtual Root URL, and Sites fields.

    The Host Name field is the unique identifier for the WebRoot instance. This can be used in render tags to get a specific vanity URL of an asset.

    The Root URL field is typically the URL used to render the asset in delivery environment. This is the URL that is used for display for the Content Contributor.

    The Virtual Root URL has two parts:

    • Environment: The identifier for the other environments. Environments must be identified by setting sites.environment=<name> in the wcs_properties.json file. Set this property from the Property Management Tool in the Admin interface. For instructions, see the Properties in the Core Category in Property Files Reference for Oracle WebCenter Sites.

    • Root URL: This is the URL that is used to render the asset in other environments such as editorial, staging, and so forth.

    To add additional virtual URLs, additional lines of Environment and Root URL fields are added by clicking the Add New button.

    Select one or more sites. The WebRoot can be enabled for specific sites using the Sites field.

  4. After all information is added, click the Save icon. The WebRoot is updated.
34.1.2.5 Approving and Publishing a WebRoot

WebRoot can be approved for publishing in the same way other assets are.

  1. Click the green checkmark icon when previewing the WebRoot.
  2. The administrator must approve and publish the WebRoot separately. WebRoots are not set as blocking assets.

34.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 34-4 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:

34.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.

  1. Click a function to show it after the pattern field.

    It does not make a difference where the cursor is located, the new pattern is always the last item. The following table provides a list of predefined functions:

    Predefined Functions Description
    spaceToUnderscore(java.lang.String)

    Converts spaces to _. For example: Page 001 would become Page_001.

    formatDate(java.util.Date, java.lang.String)

    Formats a date to a number and slash format. For example, if updatedate was "Thu Feb 28 12:57:12 UTC 2013", using the formatDate function it displays as "2/28/2013". The string used should match that used by Java's SimpleDateFormat function.

    spaceToDash(java.lang.String)

    Converts a space to -. For example, Page 001 would become Page-001.

    listAsPath(java.util.List, int)

    Converts an array to a list, for the first x items. For instance, if an array looked like [1, 2, 3 ,4, 5, 6] then using listAsPath with x = 4 the resulting list would appear as 1\2\3\4.

    Note that x, defined by int, is required.

    getFileName(com.fatwire.assetapi.data.BlobObject)

    Gets the file name for a blob object as text. For instance, if the blob name was xyz.png this would return the text xyz.png. Normally this is the very last parameter used, so that the correct file extension is present.

    This function cannot be used for binary fields of the Asset Maker asset.
    property(java.lang.String, java.lang.String, java.lang.String)

    Reads a property from ini file or a property file. This uses ics.GetProperty. Parameters for this method are 1) property name, 2) default value if the property is not present and 3) comma separated list of file names.

    getPagePath(long, java.lang.String, java.lang.String, boolean) Gets URL of the Page Asset based on the hierarchy in SiteNavigation. If the boolean parameter is true, then it converts the spaces in the URL to -.

    Functions are specified using the format ${f:<name>(<variables>)}, so for the spaceToUnderscore example given above the function would be written as 

    ${f:spaceToUnderscore("Page 001")}
  2. If you make a mistake or pass in an invalid parameter, then in the Evaluate URL Pattern section a null is returned for that part of the path. While only the outermost variable must contain ${}, all functions must begin with f:.
34.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."

Figure 34-6 URL Pattern Form - Asset

Description of Figure 34-6 follows
Description of "Figure 34-6 URL Pattern Form - Asset"

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
34.1.3.3 Deleting Patterns

Patterns can be deleted using the navigation tree.

To delete a pattern:

  1. In the General Admin tree, expand the Admin node, expand the Asset Types node, and then double-click the asset type containing the pattern.

    The selected asset type expands.

  2. Double-click URL Pattern.

    The currently saved patterns are displayed and can be inspected, edited, or deleted as any other asset.

34.1.3.4 About Publishing URL Patterns

Patterns are automatically published with the asset type. There is no special approval or publishing required for URL patterns.

34.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.

For example,

JAVA_OPTIONS=$JAVA_OPTIONS -Dsites.disablevanityurl="true"

34.2 Using Vanity URL with System Tools

Often administrators like to view all the vanity URLs defined across the system in one place, for example, to resolve conflicts. Using the System Tools node, an administrator can view all presently defined vanity URLs and resolve URL conflicts as the following sections describe:

34.2.1 Viewing All Vanity URLs

To view all vanity URLs:

  1. In the General Admin tree, expand the Admin node, expand the Asset Types node, and then expand the System Tools node.
  2. Double-click URL.

    The URL Utility Form opens.

Figure 34-7 URL Utility Form

Description of Figure 34-7 follows
Description of "Figure 34-7 URL Utility Form"

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.

34.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.

  1. 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.
  2. This issue can be mitigated by ensuring that the WebRoot is unique to a single site.

34.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 when sample sites are installed. Values are set in the site.prefix property.

To enable the rewriter filter:

  1. In the General Admin tree, expand the Admin node, expand the WebRoots node, and then double-click Add New.
    The WebRoot edit form opens.
  2. Create a WebRoot.
  3. In the Admin interface, open the Property Management Tool, and search for the site.prefix property. (For instructions on accessing the Property Management Tool, see the Properties in the Core Category in Property Files Reference for Oracle WebCenter Sites.)
  4. Add the newly created WebRoot to the comma separated value of site.prefix property.
  5. Restart the server.

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

34.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:

  1. WebRoot must be set for the Mobile domain names. The Root URL of the WebRoot should have mobile domain names.
  2. 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.
  3. 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.

34.5 Using the Web Server with Vanity URLs

If there is a requirement to access vanity URLs in a similar way to the filter and you want to have all the control and power that URL rewriting entails, you can use a web server.

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 sees the WebRoot (full server name, port and prefix if absolute WebRoot, or only the prefix if relative WebRoot). The lookuppage sees 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

34.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.

Topics:

34.6.1 Setting Up mod_rewrite

To set up mod_rewrite:

  1. Enable mod_rewrite by editing httpd.conf and uncommenting the following line:
    LoadModule rewrite_module modules/mod_rewrite.so
  2. Enable the Rewrite engine by adding this line to httpd.conf:
    RewriteEngine On
  3. For debugging, only enable logging on mod_rewrite (this is very high cost operation so only use it when debugging):
    LogLevel alert rewrite:trace6
  4. Save the changes to httpd.conf; mod_rewrite is now enabled (without any rules). Ensure the web server starts.

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.

34.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/Surfing

      lookuphost=http://www.example.com &lookuppage=/Page/Surfing

    • http://www.example.com/Article/Baker_Likely_to_Stay_With_Stars

      lookuphost=http://www.example.com &lookuppage=/Article/Baker_Likely_to_Stay_With_Stars

    • http://www.example.com/Home

      lookuphost=http://www.example.com &lookuppage=/Home

    • http://www.example.com/Home?time=true

      lookuphost=http://www.example.com &lookuppage=/Home&time=true

  • Development:

    • http://dev.example.com:8080/Running/Home

      lookuphost=/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

34.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:

  • ^ — start of line indicator

  • (.*) — s select match all text indicator; placing it in parentheses also saves that text to a variable

  • $ — end of line indicator

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:

  • /<context>/Sites — the Sites Context Root (cs) followed by the vanity URL filter (Sites)

  • ? — indicates that parameters coming after this are query parameters

  • lookuphost=http://www.example.com

    • lookuphost — provides the vanity URL filter with the name of the WebRoot

    • http://www.example.com — the WebRoot for the production server (it is an absolute WebRoot).

It informs mod_rewrite that this is the end of the rules. All mod_rewrite rules must end with this.

34.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_Stars
and 
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
To handle the query parameter, do the following:
  1. Use a mod_rewrite built-in variable "%{QUERY_STRING}" to update the /<context>/Sites? lookuphost=http://www.example.com& lookuppage=$1 rule:

    to:

    /<context>/Sites? lookuphost=http://www.example.com& lookuppage=$1&%{QUERY_STRING}

    If no Query parameters are passed in the URL then %{QUERY_STRING} is empty. Thus it will work for the three previous URLs, and also for this URL.

  2. Next, look at the Development URL:
    http://dev.example.com:8080/Running/Home

    This must be passed in to the vanity URL filter as:

    lookuphost=/<context>/Avi&/<context>/Sites?lookuppage=/Running/Home

    Because mod_rewrite does not deal with host and port by default (there are special parameters that contains this information), the rewrite rule is very similar to the following rule: 

    RewriteRule ^(.*)$ /<context>/Sites?lookuppage=$1&lookuphost=/<context>/Avi [L]

    In this case because development utilizes a relative WebRoot, we have to adjust the name; as the rest of the URL is unchanged the same rule still applies.

34.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.

The following example uses http://www.example.com/Page/Surfing as the URL, which expects /<context>/AVISPORTS/Page/Surfing:
  1. To handle the above URL, create a new mod_rewrite rule:
    RewriteRule ^(.*)$ /<context>/AVISPORTS$1 [L]

    This rule simply takes what is given and prefixes /<context>/AVISPORTS to it.

    The same rule works for:

    http://www.example.com/Article/Baker_Likely_to_Stay_With_Stars and http://www.example.com/Home
  2. To handle http://www.example.com/Home?time=true, add the %{QUERY_STRING} parameter to the rule, so it becomes:
    RewriteRule ^(.*)$ /<context>/AVISPORTS$1?%{QUERY_STRING}  [L]
http://www.example.com/Home?time=true

34.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.

  1. Use the following example and assume that the CSS files are kept in a directory named AVISPORTS_STATIC:
    http://www.example.com/Page/Surfing
  2. To handle this, a second mod_rewrite rule is required. This rule precedes the former rule which ensures that calls to this directory are not rewritten.

    This can be written as:

    RewriteRule ^.*/AVISPORTS_STATIC/(.*)$ /<context>/<site-prefix>/$1 [L,PT].

    With these two rules, the first ensures that all static pages and CSS are not converted to a vanity URL, and the second rule (which was constructed in About Converting with mod_rewrite) sends the remaining URLs to the vanity URL filter. 

    RewriteRule ^.*/AVISPORTS_STATIC/(.*)$ /<context>/<site-prefix>/$1 [L,PT]
RewriteRule ^(.*)$ /<context>/Sites?lookuphost=http://www.example.com&lookuppage=$1&%[QUERY STRING} [L]

34.7 Customizing Vanity URLs

WebCenter Sites allows you to customize auto-generated vanity URLs, so that you can dynamically set them.

The system checks for the presence of custom elements in pre-defined locations, before an asset is saved. The presence of the following custom elements, according to precedence, is checked:

  • 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.

If a custom element is found, it will be executed.

Note:

Only one element according to precedence is executed.

Table 34-5 describes the two objects that are available in the element scope: assetData and webrefs.

Table 34-5 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.

34.7.1 Creating a Customized Vanity URL

The following example explains how to create a customized vanity URL.

Assume that for assettype AVIArticle in avisports site, you would like to add a vanity URL with category and assetid for AVIArticle assets. You can create this customized URL by the following steps:
  1. In the Admin UI, navigate to the General Admin tree. Under the Admin node, expand Asset Types, and then expand the asset type for which you want to create a customized vanity URL. In this case AVIArticle, as shown in the following figure.
  2. 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.

    Figure 34-8 Create an URL Pattern

    Description of Figure 34-8 follows
    Description of "Figure 34-8 Create an URL Pattern"
  3. 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 34-9 Create a Groovy Element Using Sites Explorer

    Description of Figure 34-9 follows
    Description of "Figure 34-9 Create a Groovy Element Using Sites Explorer"
  4. Add the following lines to the element and save it. 
    /* 
* This element is invoked during asset save. It lets users to edit the webreferences for the asset. Following objects are available in ics scope when this element is called
* assetData - updated values of the asset that is being saved 
* webrefs   - list of auto generated webreferences for this asset (input/output)
* 
* Webreferences available in ics will be associated with current asset being saved. Any changes to assetData object are ignored. 
*/

import com.fatwire.assetapi.data.* 
import java.util.*

String token = "__my_custom_url__" 

// get the asset data and form the vanity url based on asset data 
AssetData aData = AssetData.class.cast(ics.GetObj("assetData"))
String category = aData.getAttributeData("category").getData()[0]
String id = String.valueOf(aData.getAssetId().getId())
String url = category+"/"+id 

// get the auto generated webreferences and iterate over the list
List webrefs = List.class.cast(ics.GetObj("webrefs"))
Iterator it = webrefs.iterator()
while(it.hasNext())
{ 
	WebReferenceImpl webref = 
WebReferenceImpl.class.cast(it.next())
	// replace existing token with asset data
	if(webref.getAssetUrl().equals(token)) {
		webref.setAssetUrl(url)
	} 
}

    This code reads the AssetData of the current asset and auto generated webreferences from ics object. It reads the category and asset id from AssetData and dynamically creates a new URL. It then loops over all the webreferences to locate one with the static token and then replaces it with the newly formed URL.

    Note:

    Changes to assetData object does not affect the asset. You can add, remove or update webreferences in webrefs object. All the webreferences given by the webrefs object will be assigned to current asset.
  5. Edit and save an Article asset of site avisports to see the custom vanity URL assigned to the asset.