OracleAS Portal Developer Kit (PDK)
How to Add Remote Portlets Using the Federated Portal Adapter

Introduction

The Federated Portal Adapter is a component of OracleAS Portal which allows portal instances to share database portlets via the Web portlet interface.

This article describes how to:

• set up the environment so that the registered provider works correctly
• register a provider through the Federated Portal Adapter
• write portlets that behave correctly when accessed through the Federated Portal Adapter.

Assumption

You have read and understood the article Understanding the Federated Portal Adapter.

Setting Up the Environment

Distinguishing Between Portals

All portals accessed via Federated Portal Adapter must have different schema names. Portals installed by Oracle Universal Installer are called 'portal' by default and it is not possible to change the name of a schema once it has been created. It is important then that if you intend to use a portal with the Federated Portal Adapter you specify a non-default schema during installation of that portal.

Also all portals accessed via Federated Portal Adapter must have different DAD names, and the cookie names must match the DAD names. If this is not the case then a portal's cookie name and DAD name must be altered.

Sharing a Login Server

portal session information is passed to a remote portal which is used by the Federated Portal Adapter to create a session.

For example, if a user 'JSMITH' displays a portal page and a portlet on that page is sourced from the HTTP PL/SQL Adapter on a remote portal, a session is created on the remote portal for user 'JSMITH'. If the two portals do not share a Login Server then 'JSMITH' may be the username for 'John Smith' on one portal and 'Jane Smith' on the other.

Typically, this is solved by sharing a Login Server between the two portal instances. If the portlets being shown are 'public' there is no need to share a Login Server, as a public portal session is created at the remote portal instance.

Message Authentication

Since the Federated Portal Adapter creates private portal sessions based on SOAP messages it receives, there is a potential security risk. This is addressed by the inclusion of a message authentication code to each SOAP message which the remote portal verifies before creating a private session. Once implemented, this algorithm ensures that the SOAP message received is from a trusted source- it doesn't encrypt the message. HTTPS should be used if that is desired.

If 'Portal B' wishes to expose providers to users of 'Portal A', a private 'key' must be stored on each portal. This key is used to encode portions of each SOAP request sent between them. If the encoding at the receiving end matches the encoding at the sending end then a private session can be created. If a key is missing, or they are different on each portal, only PUBLIC sessions are created.

The key must be at least 10 characters long, and administrators should inform each other of key values in a suitably secure way.

These SQL scripts are provided to maintain the key store:

In each case, both sending and receiving refers to the SOAP message. In the example above, 'Portal A' is the sender (sending SOAP and show requests) and 'Portal B' is the receiver of those requests.

If provider sharing is required both ways, then this process must be repeated the other way round, possibly with different shared keys. It should also be noted that a portal can expose its providers to several other portal instances, i.e. 'Portal A' can expose providers to 'Portal B' and 'Portal C' and separate keys can be set up between each portal instance pair.

Setting the Cookie Domain

Cookies received by a browser, or other HTTP client, are sent to servers if the domain of the cookie matches the server's host name. For example, cookies with the domain '.co.uk' and 'mycompany.co.uk' are sent with a request to 'http://mycompany.co.uk/pls/etc/etc'.

By default, the scope of cookies created by portal is restricted to the host name of the middle-tier machine. Since communication with portlets takes place in the middle-tier by the Parallel Page Engine (PPE) and not the browser, the session cookie for the remote portal is not sent when there are links with a remote portlet. Also, the remote portal session cookie is not sent during the show request for the remote portlets.

This is solved by widening the scope of the cookies created by portal and making sure that the cookies received by the PPE are sent back to the browser (see Step 3 of Registering a Provider below). Widening the scope of cookies created by portal is achieved by running the SQL script wwc/ctxckupd.sql.

For the next example, there are two portals:

• http://myhost1.mycompany.co.uk:3000/pls/portalA
• http://myhost2.mycompany.co.uk:4000/pls/portalB

...and a provider is registered from 'Portal B' onto 'Portal A'.

By default, when showing a page on 'Portal A' that contained a portlet from 'Portal B' a portal session cookie for 'Portal B' (domain is 'myhost2.mycompany.co.uk:4000) is created, and sent to the PPE. If the 'Web provider in same cookie domain as the portal' property is checked on the provider registration page, this cookie is sent back to the browser. In this example the domain of the cookie will be 'myhost1.mycompany.co.uk:3000' because that is where it is sent from, i.e. the PPE is at 'myhost1.mycompany.co.uk:3000'.

If a link is followed from within the portlet the cookie is not sent with the request, as the domain of the cookie doesn't match the host of the request.

To solve this problem, connect to SQL*Plus as the portal owner of each portal, run wwc/ctxckupd.sql and set the 'Broaden the Scope of the Domain Cookies created by portal' so each portal is in the same domain. Once this is done, the scope of the cookie domains created by any of the portals is broad enough so they are sent back to the browser and links within the portlet work correctly.

Registering A Provider

Registering a provider through the Federated Portal Adapter is like registering any Web provider. However, there are a few things worth noting as follows:

1. On the first page of the Register Provider screen, enter Name, Display Name, Timeout and Timeout Message values as normal but make sure the Implementation Style is set to 'Web'.

   Note: Although the provider is actually written in PL/SQL all communication to it is as a Web provider and not a database provider, therefore the Implementation Style is 'Web'.

2. On the second page, enter the URL of the adapter service in the form:

   http://<host>:<port>/adapter/<dad>/<schema>

   Or, if the DAD and the schema are the same, you can just use:

   http://<host>:<port>/adapter/<dad>'

   where the <host>, <port>, <dad> and <schema> locate the remote portal instance.

   Note: You can verify that this is the correct URL by pasting it into a browser.  If the URL is correct the message "Congratulations - you got to the adapter test page" is displayed.

3. Check the Web provider in same cookie domain as the portal check box.

   Note: This ensures that cookies generated from the provider are sent back to the browser. It may be necessary to Broaden the scope of the cookies created by portal as described above.

4. Enter the Service Id. This should be in the form 'urn:<provider name>'. Where <provider name> is the name of the provider on the remote portal instance. This is both case sensitive and upper case. 

   Note: This is the information that the Federated Portal Adapter uses to locate the specific provider at the remote portal. For page groups exposed as providers, the name of the provider will be something like 'MYPAGE970D272EBE9D2D0FE034080020F7DA4B' and it is important that you specify this Name rather than the Display Name.

5. In the User/Session Information section select the User radio button and set the Login Frequency to be 'Once Per User Session'.

   Note: These settings make sure that information is sent with the request to allow a portal session to be created on the remote portal instance.

Writing Portlets That Use the Federated Portal Adapter

Relative Links

If portlets accessed through the Federated Portal Adapter contain any links, they must be absolute links rather than relative. Relative links do not work as they are relative to the local middle-tier rather than the remote middle-tier. For example, use links in the form 'http://myhost.mycompany/etc/etc' rather than just '/etc/etc'.

Customization

When accessing portlets through the Federated Portal Adapter, the sequence of events when submitting a customization form is as follows:

1. Page submits to the 'local' PPE.

   There are several standard parameters that need to be sent with this submission (e.g. _providerid, _dad, p_action etc.) as well as the parameters that are being customized. A procedure called wwpro_api_adapter.open_form simplifies this submission.

2. PPE shows the customization page again.

   The 'p_action' parameter is set during the show_portlet call to one of:

   • 'OK' - Customizations are saved, followed by a re-direct to the page containing the portlets.
   • 'APPLY' - Customizations are saved and the customization page displayed.
   • 'RESET' - Default values for parameters are queried and the customization page displayed.

So, these areas of portlet code need to be changed to make customizations work through the Federated Portal Adapter:

• The show call of the portlet needs logic to show the portlet in edit_defaults mode, or customize mode if the parameter 'p_mode' is null. If the 'p_mode' parameter is one of 'OK', 'APPLY' or 'RESET' then the customizations must be saved as appropriate and re-directed as described above.
• The <FORM> HTML tags generated for the customization page must be created using the procedure wwpro_api_adapter.open_form . This ensures that the action for the form is correct and the correct parameters are passed in the page submission.

Hints and Tips on Usage

Portal Database Providers

Portal database providers created using Oracle Portal contain the necessary code to run via the Federated Portal Adapter. This means that applications created containing forms, charts, reports, etc. can be shown on any other portal instance.

Pages

Pages exposed as portlets can also run via the Federated Portal Adapter. Regions within pages can contain portlets or items and using the Federated Portal Adapter, these can now be accessed from any portal instance.

User-Created Providers

If you create your own PL/SQL providers, they can be exposed through the Federated Portal Adapter, providing they are coded in accordance with the guidelines given in this document.