URL Mapping

 

+
Search Tips   |   Advanced Search

 

 

Contents

  1. Overview
  2. Administrative model
  3. Tasks
  4. Unreserved URL characters.

 

Overview

URL Mapping allows portal administrators to create constant user friendly URLs and map them to portal pages. As administrators create the URLs, they can define human readable names for them. These can be easily remembered and are therefore more user friendly. 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 prefix that was defined by the store, for example...

http://www.setgetweb.com/wps/portal/tech/mystuff

Clicking on such a mapped URL from outside of the portal takes the user to the desired portal page. Users can also combine several mapped contexts into the representation of a full valid URL, type that full 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 desired 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 desired page. However, this works only if portal security is enabled.

 

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 above is the URL concatenated from the three contexts.

The following context attributes can be configured for the URL contexts:

The following restrictions apply to the names you can give to contexts:

  1. Users can map contexts to all portal pages for which they have the User role.
  2. As the labels are later used to create the URL, the label can only contain characters that are in the set of unreserved URL characters. For more information see Reference: Unreserved URL characters.
  3. A label of a context must be unique in the scope of its parent context. This means that no two sibling contexts can have the same label.
  4. 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. See Defining the identifier for portal URLs for more information.
  5. The maximum length of a label is restricted to 255 characters.

 

Mapped URLs and their hierarchy

The complete user defined URLs are concatenated from the context hierarchy as described above. They are mapped to portal pages as shown in the following example:

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/ThinkPad
Software Products/Software Software page

 

Portal content tree and URL Mapping context tree

The hierarchical tree of the contexts is independent from that of the portal pages and navigation. This has the following advantages:

 

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 above, 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/ThinkPad
Software Products/Software

Notes:

  1. 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 above, if user S has no access role for the Products context, user S cannot edit or map that context. User S can only view and click that context in the URL mapping portlet, in order to get to the Hardware context for which the user has the Editor access role.
  2. Use of explicit blocks overrules the default inheritance behavior. If in the example above the administrator puts a block on the Laptops context for user S, then user S cannot map that context to a portal page or create a child context under it, such as Subnotebooks in the example above.

The access control roles required for the URL Mapping tasks are listed in the following table:

Mapping URL task Required role
Create a context Editor role for the parent context
Deleting a context Manager role for the context
Adding, removing, or changing a label Editor role for the context
Mapping tasks:

  • Mapping a portal page to a context
  • Changing a mapping
  • Removing a mapping

Both of the following:

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

Recommendation: Although an administrator can allow end 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.

Refer to the section about Securing your portal and especially about Authorization and Access rights for more information about how to administer user roles and access rights.

 

Work with the URL Mapping feature

Administrators perform the following tasks related to URL Mapping:

These tasks are described in the following sections.

 

Administer the Mapping URL hierarchy

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

See the help of the URL Mapping portlet for detail on how to perform these tasks.

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:

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 the file 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>

Notes:

  1. 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.
  2. If you 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, edit the property wps.mappingurl.enabled in the file ConfigServices.properties. Set the value to true to enable URL Mapping; set the value to false to disable URL Mapping. This 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, 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.

You can configure this identifier according to your preference. However, the following restrictions apply:

  1. 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.
  2. The identifier may only contain characters that are in the set of unreserved URL characters.
  3. The identifier must not start with one of the special characters that are 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, edit the parameter wps.mappingurl.portal_url_identifier in the file ConfigService.properties. The format of the identifier must be as follows: 

     /identifier_name/identifier_value

The identifier name is mandatory; the identifier value is optional.

If you change the portal-url-identifier make sure you also update the form-login-page entry in the file web.xml. For Example, if the identifier is /purl/ then the original URL /portal/.scr/Login must be changed to /portal/purl//.scr/Login .

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

 

Special characters:

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

See also