URL Mapping

URL Mapping

Overview
The administrative model of URL Mapping
Mapped URLs and their hierarchy
Portal content tree and URL Mapping context tree
Access control administration
Work with the URL Mapping feature
Administer the Mapping URL hierarchy
Administer access roles for the context tree
Configure URL Mapping
Reference: Unreserved URL characters
Set the language for a URL Mapping

Portal administrators can create constant URLs and map them to specific portal pages. When administrators create constant URLs, they define human-readable names for the URLs that are easy to remember and retrieve.
The self defined URLs can be published externally and thereby made available to portal users.
For example, a computer store that uses the portal could create a user defined URL...
products/hardware/laptops

...for the page on which their laptop product line is advertised. This URL can be appended to a portal prefis that was defined by the store, for example...
http://www.fancy_xyz_computers.example.com/wps/portal/products/hardware/laptops

Clicking on such a mapped URL from outside of the portal takes the user to the required portal page. Users can also combine several mapped contexts into the representation of a full valid URL, type that fully mapped URL into the address field of the browser, and thereby get to the portal page.
Clicking on a mapped URL from outside the portal takes the user straight to the required page in the case of pages which are accessible without login to the portal. In the case of pages which require login the user is prompted for user ID and password. After successful login the portal takes the user directly to the required page. However, this works only if portal security is enabled. Otherwise the portal redirects the user to the portal Welcome page.

The administrative model of URL Mapping

The mapped URLs are arranged in hierarchical trees of contexts. A tree starts with a root context at the top level, and each context can have several child contexts. The full URL of a context is created by concatenating the labels of all contexts that lie on the path from the root to the given child context. The example products/hardware/laptops given earlier is the URL concatenated from the three contexts.
The following context attributes can be configured for the URL contexts:

The label or labels of the context:
Examples of labels are products or hardware. A context must have at least one label; it can have more than one label.

The portal page:
The portal page which the context references; in other words, the page to which the context is mapped.

Child contexts of a context.

The following restrictions apply to the names that we can give to contexts:
A label of a context must be unique in the scope of its parent context. No two sibling contexts can have the same label.

When creating a URL Mapping or creating or modifying a page, make sure that URL Mappings and friendly URLs in the portal do not match, partially overlap, or otherwise interfere with each other.
For example, do not use strings such as home, ibm, ibm.com, and do not use strings that have been used as URL Mappings or friendly URLs in the portal already. Otherwise infinite browser redirect loops might occur, sometimes without an error message. To determine such strings, create an export from the portal using xmlaccess.sh and scan the exported XML result output file for the string to use for the URL Mapping or for the friendly URL.

Users can map contexts to all portal pages for which they have the User role.

As the labels are later used to create the URL, the label can only contain characters in the set of unreserved URL characters.

The label of a root context must not share its partial or full name string with a portal URL identifier. Example: If the identifier is name, then a root context must not be na or vice versa.

The maximum length of a label is restricted to 255 characters.
A label must not have the same name as URL codecused in the portal. Here is a lists of codec names that are currently in use and therefore reserved:
base64xml, b0, b0_1, b0_2, b0_3, b1, b2, b3, 
c0, c0_1, c0_2, c1, c2, c3, c4, c4_1, c4_2, c4_3, c5, c6, c7, 
cxml, cxmld, cxml_1, cxml_2, kcxml, d0, d1, d2, d3, d4, d5, delta, dl2, dl3, dl4, 
kcxml, nm1, nm2, nm3, nm4, pw, resource, sel, vp, wml
Mapped URLs and their hierarchy

The complete user defined URLs are concatenated from the context hierarchy as described previously. They are mapped to portal pages :

are
Context hierarchy URL name Referenced page
Products Products Product page
   Hardware Products/Hardware Hardware page
      Laptops Products/Hardware/Laptops Laptop page
   Software Products/Software Software page

The context Laptops references the Laptop page, therefore this page can be accessed via the URL Products/Hardware/Laptops.
If a context has more than one label, this results in the equivalent number of possible URLs combined from context names. In the following example, the Laptop page can be accessed by both the URLs Products/Hardware/Laptops and Products/Hardware/ThinkPads:

Context hierarchy URL name Referenced page
Products Products Product page
   Hardware Products/Hardware Hardware page
      Laptops Products/Hardware/Laptops Laptop page
      ThinkPads Products/Hardware/ThinkPads Laptop page
   Software Products/Software Software page

Portal content tree and URL Mapping context tree

The hierarchical tree in this example contains entries for products, hardware, laptops, and software separate from the content tree. The hierarchical tree of the contexts is independent from that of the portal pages and navigation :
This has the following advantages:

Users can map contexts and URLs for which they have the Editor role to all portal pages for which they have the User role.

Administrators can give users access roles to individual contexts. These roles determine the access rights assigned to the users to perform their tasks.
For example, if you give a user the Editor role to contextso that user can then map those contexts to pages.

If you change the name or label of a context, the portal applies that change to all user defined URLs which depend on that context. Example: an update from...
products/hardware/..

to...
products/computer-hardware/...

...changes changes all URLs under the updated context accordingly.

Access control administration

Administrators give users access roles to perform their tasks with contexts. The roles determine the access rights assigned to the users to perform their tasks. The roles given to a user for a single context are inherited by all its children by default.
The following example can explain this: Administrator A assigns subadministrator S the Editor access role for the Hardware context. By default, user S then has the same role on all children of context Hardware. In the example given previously, this would be Laptops and ThinkPads. Therefore, user S can add subcontexts at any location in this subtree. However, user S has no permission to add subcontexts to the software context or to its child contexts. In the following table, the part of the context tree for which user S has the Editor role is shown in bold.

Context hierarchy URL name
Products Products
   Hardware Products/Hardware
      Laptops Products/Hardware/Laptops
         Subnotebooks (Context added by user) Products/Hardware/Laptops/Subnotebooks
      ThinkPads Products/Hardware/ThinkPads
   Software Products/Software

Users can traverse contexts for which they have no access role assigned, in order to get to a child context for which they have an access role assigned. In the example given previously, if user S has no access role for the Products context, user S cannot edit or mas that context. User S can only view and clicthat context in the URL Mapping portlet, in order to get to the Hardware context for which the user has the Editor access role.

Use of explicit blocks overrules the default inheritance behavior. If in the example given previously the administrator puts a block on the Laptops context for user S, then user S cannot mas that context to a portal page or create a child context under it, such as Subnotebooks in the example given previously.

Mapping URL task Required role
Create a context Editor role for the parent context
Delete a context Manager role for the context
Add, remove, or change a label Editor role for the context
Mapping tasks:

Map a portal page to a context
Change a mapping
Remove a mapping

Both of the following:

Editor role for the context
User role on the portal page.

Restriction: Although an administrator can allow users to define contexts and map them to their pages, it is not recommended to do this. The number of potential URL Mappings can then grow significantly; this may have performance implications.

Work with the URL Mapping feature

Administrators perform the following tasks related to URL Mapping:

Administer the Mapping URL hierarchy
Administer access roles for the context tree
Configure URL Mapping

These tasks are described in the following sections.

Administer the Mapping URL hierarchy

We can perform the following tasks with the Mapping URL administration portlet:

Create a context

Delete a context

Add a label to a context
Remove a label from a context

Change the label of a context

Map portal pages to contextso that is assign mappings for portal pages to URL Mapping contexts

Reassign a mappings that is change the portal page that is mapped to a context

Unassign a mappings that is remove the mapping of portal page to a context.

For details about how to perform these tasks refer to the help of the URL Mapping portlet.
To get to the URL Mapping portlet, click Administration, then Portal Settings, then URL Mapping.

Administer access roles for the context tree

Administrators perform the following tasks with regard to access control roles for URL Mapping:

Assign access roles to users for a context
Remove access roles.

Use the Access control portlets to assign access roles to users for contexts.
See the help of the Access control portlets for detail on how to perform these tasks.

Configure URL Mapping

Administrators perform the tasks described in the following to configure URL Mapping: Adapting to changes of the portal servlet mappings:
The filter mappings for URL Mappings must be identical to the servlet mappings of the portal. If those are changed, the filter mappings must be updated accordingly. To do this, edit the following lines in web.xml:
     <filter-mapping>
        <filter-name>URL Analyzer</filter-name>
        <url-pattern>/portal/*</url-pattern>
     </filter-mapping>   

     <filter-mapping>
        <filter-name>URL Analyzer</filter-name>
        <url-pattern>/myportal/*</url-pattern>
     </filter-mapping>
The update is required for both versions of the file web.xml. To ensure this, redeploy the file after the update, or apply the update to both files.

If we use the modify-servlet-path configuration task, the portal performs this update, and you do not have to do it manually.

Enabling and disabling URL Mapping:
URL Mapping is enabled by default. It can be disabled. To disable URL Mapping, modify the property wps.mappingurl.enabled in Configuration Service, as described in Set service configuration properties. Set the value to true to enable URL Mapping or set the value to false to disable URL Mapping. Setting this property is sufficient if you switch between the two states regularly.
If you install the portal with the Mapping URL functionality disabled, it is strongly recommended to still define the Portal URL identifier, if a change to enabled Mapping URL functionality may become possible in the future. This is recommended, as all browser bookmarks to dynamically created Portal URLs will break when you change the identifier.
If you decide not to use URL Mapping at all, you should additionally edit the portal file web.xml in order to obtain maximum performance. Comment out the following lines:
     <filter>
        <filter-name>URL Analyzer</filter-name>
        <filter-class>com.ibm.wps.mappingurl.impl.URLAnalyzer</filter-class> 
     </filter>

     <filter-mapping>
        <filter-name>URL Analyzer</filter-name>
        <url-pattern>/portal/*</url-pattern>
     </filter-mapping>   

     <filter-mapping>
        <filter-name>URL Analyzer</filter-name>
        <url-pattern>/myportal/*</url-pattern>
     </filter-mapping>
Defining the identifier for portal URLs:
Portal URLs are the URLs that are automatically created by the portal itself. To be able to distinguish between a URL created by URL Mapping and a portal URL, portal URLs have an identifier included.
Configure this identifier according to the preference. However, the following restrictions apply:

The portal URL identifier must not share its partial or full name string with the label of a root context. Example: If the identifier is name, then a root context must not be na or vice versa.

The identifier may only contain characters in the set of unreserved URL characters.

The identifier must not start with one of the special characters in the set of unreserved URL characters.

For more information about the set of unreserved URL characters see Reference: Unreserved URL characters.
To change the identifier of a portal URL, modify the parameter wps.mappingurl.portal_url_identifier in Configuration Service, as described in Set service configuration properties. The format of the identifier must be as follows:
     /identifier_name/identifier_value
The identifier name is mandatary; the identifier value is optional.

On a running production system, this should only be performed if it is really required, as it will break existing browser bookmarks to the portal.

Reference: Unreserved URL characters

Context names and identifiers must only consist of characters that are contained in the set of unreserved URL characters. They are listed in the following. Alphanumeric characters:
  a b c d e f g h i j k l m n o p q r s t u v w x y z
  A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
  0 1 2 3 4 5 6 7 8 9
Description Character
Hyphen -
Underscore _
Period .
Exclamation mark !
Tilde ~
Asterisk *
Single quote '
Parentheses open and closed ( )

Setting the language for a URL Mapping

You might want to create a link to the portal in a specific language for portal users. In this case use a URL Mapping and set it to the required language. The portal will display the addressed page and all subsequently selected pages in the locall defined in the URL Mapping until a different language is explicitly requested. To set the language for a URL Mapping, use xmlaccess.sh:

Create the URL Mapping as required using the URL Mapping portlet.

Export the URL Mapping using xmlaccess.sh.

To change the locale for the URL Mapping, edit the resulting XML file and update the value for the locale attribute in the <portal-url> element as required.

Import the URL Mapping with the changed locale by running the updated XML script.
Using xmlaccess.sh is the only method for changing the locale of a URL Mapping.

Parent: Configure portal behavior

Context hierarchy	URL name	Referenced page
Products	Products	Product page
Hardware	Products/Hardware	Hardware page
Laptops	Products/Hardware/Laptops	Laptop page
Software	Products/Software	Software page

Mapping URL task	Required role
Create a context	Editor role for the parent context
Delete a context	Manager role for the context
Add, remove, or change a label	Editor role for the context
Mapping tasks: Map a portal page to a context Change a mapping Remove a mapping	Both of the following: Editor role for the context User role on the portal page.

Description	Character
Hyphen	-
Underscore	_
Period	.
Exclamation mark	!
Tilde	~
Asterisk	*
Single quote	'
Parentheses open and closed	( )