Consistent Portal URLs ("Deep Linking")

Owned by Laura McCord
Aug 27, 2013

URL Structure

/uPortal/f/folderName/p/portletName.subscribeId/state/render.uP

  • The folderName specifies which layout folder to render under
    • {0..N} folderName elements are allowed in the path to handle sub-tabs and other such cases
    • The /f/ prefix folder defines that the next path section(s) are folder names
    • The folder section (/f/ prefix and folder parts) are optional and can be left out when manually creating a URL that targets a specific portlet
  • The portletName.subscribeId specifies the targeted portlet
    • Used for all url types when in a targeted WindowState such as max, detached, and exclusive.
    • Used for all action and resource requests
    • portletName is the portlet's fname
    • subscribeId is the ID associated with that particular subscription to the portlet in the user's layout.
    • The /p/ prefix folder defines that the next path section is a portlet
  • The state specifies the style of the page being rendered.
    • normal - Standard portal page, tab with multiple portlets
    • max - One maximized portlet, portal provides chrome, tabs and perhaps other UI elements
    • detached - One detached portlet, portal provides <head> element, all visible content is rendered by the portlet
    • exclusive - One exclusive portlet, portlet renders all of output, binary content is allowed here
    • If the state is not specified then normal will be used when targeting a folder and max will be used when targeting a portlet
  • The render is the type of URL being requested.
    • render - a URL that renders content, also used for a portlet RenderRequest
    • resource - a URL that serves a portlet resource (ResourceRequest)
    • action - a URL that executes a portlet action (ActionRequest), this URL may not render content and must return a 3xx class code.
    • If the type is not specified render is assumed

Syntax Notes

  • If a portletName.subscribeId is specified but the subscribeId does not exist for the current user it is ignored and the following resolution rules are used:
    1. The first instance of the named portlet on the user's layout
    2. A transient portlet loaded by fname if the user has permission to view the portlet
    3. The user ends up at their default tab
  • Partial URLs are valid
    • /uPortal/p/portletName 
      • Targets portletName in maximized mode with a render request
    • /uPortal/p/portletName?someParam=foo
      • Targets portletName in maximized mode with a render request and the portlet parameter someParam=foo
    • /uPortal/p/portletName/detached?someParam=foo
      • Targets portletName in detached mode with a render request and the portlet parameter someParam=foo
    • /uPortal/p/portletName/resource.uP?someParam=foo
      • Targets portletName in maximized mode with resource request and the portlet parameter someParam=foo

Future Goals

  • Require that all navigable layout folders (tabs, subtabs, etc) have a URL friendly fname assignment
  • Only include the portlet subscribeId if the user has that portlet subscribed multiple times under the folder specified in the URL

Canonical URLs

After parsing the requested URL the portal will generate a new, canonical, URL string using the parsed data. If the canonical URL doesn't match the requested URL a redirect is sent so that the user's browser always displays the same URL for the same piece of content.

Deep Linking with Authentication (refUrl)

Things can get a bit tricky when you want to display "deep linked" content and authenticate the user at the same time.  The uPortal /Login servlet supports the refUrl parameter for this purpose.  The value should be a valid, URL-encoded portal URL.

 

Deep Linking + CAS Authentication Example

This example is using the included cas authentication.  If the authentication is not standard, your results may vary.

This url sends the user directly to a maximized portlet with ‘fname’ if they are already authenticated within the same browser instance.  If they are not authenticated, they will be sent to the authentication page and then directly to the maximized portlet if they are authorized for that portlet.

http://ourhost:port/cas/login?service=ourhost:port/uPortal/Login?refUrl=/uPortal/p/fname

I’ve tried using the tag like you suggested but I got the same results (redirect to the default layout)

Double Encoding

Option 1: Apache Rewrite Rules

RewriteRule ^/tab/(.*)
https://lcas.university.edu/cas/login?service=https\%3A\%2F\%2Fmy.manchester.ac.uk\%2FuPortal\%2FLogin\%3FrefUrl=/uPortal/f/$1
[L,NE]
RewriteRule ^/portlet/(.*)
https://cas.university.edu/cas/login?service=https\%3A\%2F\%2Fmy.manchester.ac.uk\%2FuPortal\%2FLogin\%3FrefUrl=/uPortal/p/$1
[L,NE]

It looks like the parameter name "refUrl" can get tricky involving double encoding in certain use cases. 

Option 2: Reconstruct the URL

If rewrite rules isn't an option for you, construct the URL with the understanding that each time the url is fed through the system it will have things encoded and plan for that. The following would be an example to deep link into the announcements portlet: 

https://cas.university,edu/cas/login?service=https://school.edu/uPortal/Login%3frefUrl=/uPortal/p/announcements/max/render.uP%3fpP_action=displayFullAnnouncement%2526pP_announcementId=1834

The tricky part is the "%2526" at the end. After the first pass through the %25 will be translated to a "%" symbol resulting the string "%26" which on the second pass through will be translated into a "&" and subsequently adding the pP_announcementId parameter to the URL. 

 

 

Having problems with these instructions?

Please send us feedback at uportal-user@lists.ja-sig.org