+

Search Tips   |   Advanced Search

URL Mapping

  1. Overview
  2. The administrative model of URL Mapping
  3. Mapped URLs and their hierarchy
  4. Portal content tree and URL Mapping context tree
  5. Access control administration
  6. Work with the URL Mapping feature
  7. Administer the Mapping URL hierarchy
  8. Administer access roles for the context tree
  9. Configure URL Mapping
  10. Reference: Unreserved URL characters
  11. 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...

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

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 following restrictions apply to the names that we can give to contexts:

  1. A label of a context must be unique in the scope of its parent context. No two sibling contexts can have the same label.

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

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

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

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

  6. The maximum length of a label is restricted to 255 characters.

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


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

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

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

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:

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:

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>

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

  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 in the set of unreserved URL characters.

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

  1. The identifier name is mandatary; the identifier value is optional.

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

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

  2. Export the URL Mapping using xmlaccess.sh.

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

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