Oracle9iAS Portal Developer Kit (PDK)
Understanding External Applications for URL-Based Portlets

Introduction

URL-based portlets allow developers to take any application written in any language and easily create integrated portlets.

This article describes the details of using the PDK to create a URL-based portlet from a secured external application, such as My Yahoo!

Understanding the Provider Definition File

The following code shows a sample provider.xml file for creating a portlet from a secured external application (in this case, Yahoo! Finance).

<?xml version="1.0" encoding="UTF-8"?> <?providerDefinition version="3.1"?> <provider class="oracle.portal.provider.v2.http.URLProviderDefinition">   <providerInstanceClass>oracle.portal.provider.v2.http.URLProviderInstance</providerInstanceClass>   <session>true</session>   <authentication class="oracle.portal.provider.v2.security.Authentication">     <authType>ExternalApp</authType>     <userFieldName>login</userFieldName>     <userPwdName>passwd</userPwdName>     <errorPageMessages>Invalid Yahoo ID,Invalid Password,Please sign in,Sign me up!</errorPageMessages>   </authentication>   <proxyInfo class="oracle.portal.provider.v2.ProxyInformation">     <httpProxyHost>gatekeeper.idc.oracle.com</httpProxyHost>     <httpProxyPort>80</httpProxyPort>   </proxyInfo>   <portlet class="oracle.portal.provider.v2.http.URLPortletDefinition">     <id>1</id>     <name>YahooFinancePortlet</name>     <title>Yahoo Finance Portlet</title>     <description>This portlet is to test Integration services using finance.yahoo.com</description>     <timeout>100</timeout>     <timeoutMessage>yahoo timed out</timeoutMessage>     <showEdit>true</showEdit>     <showEditDefault>false</showEditDefault>     <showPreview>false</showPreview>     <showDetails>false</showDetails>     <hasHelp>true</hasHelp>     <hasAbout>false</hasAbout>     <acceptContentType>text/html</acceptContentType>     <registrationPortlet>false</registrationPortlet>     <accessControl>registered</accessControl>     <renderer class="oracle.portal.provider.v2.render.RenderManager">       <renderContainer>true</renderContainer>       <showPage class="oracle.portal.provider.v2.render.http.URLRenderer">         <pageUrl>http://finance.yahoo.com/p?v&amp;k=pf_2</pageUrl>         <contentType>text/html</contentType>         <filter class="oracle.portal.provider.v2.render.HtmlFilter">           <headerTrimTag>&lt;table>&lt;tr>&lt;td align=center colspan=2></headerTrimTag>           <footerTrimTag>Yahoo! Finance Home&lt;/a></footerTrimTag>           <convertTarget>true</convertTarget>           <useAuthLinks>true</useAuthLinks>           <redirectUrlFieldName>.done</redirectUrlFieldName>         </filter>       </showPage>       <editPage class="oracle.portal.provider.v2.render.http.URLRenderer">         <pageUrl>http://edit.finance.dcx.yahoo.com/e0?u</pageUrl>         <contentType>text/html</contentType>         <filterType>text/html</filterType>         <filter class="oracle.portal.provider.v2.render.HtmlFilter">           <convertTarget>true</convertTarget>           <useAuthLinks>true</useAuthLinks>           <redirectUrlFieldName>.done</redirectUrlFieldName>         </filter>        </editPage>       <helpPage class="oracle.portal.provider.v2.render.http.URLRenderer">         <pageUrl>http://help.yahoo.com/help/fin/</pageUrl>         <contentType>text/html</contentType>         <filter class="oracle.portal.provider.v2.render.HtmlFilter">           <convertTarget>true</convertTarget>           <useAuthLinks>true</useAuthLinks>           <redirectUrlFieldName>.done</redirectUrlFieldName>         </filter>       </helpPage>     </renderer>     <securityManager class="oracle.portal.provider.v2.security.URLSecurityManager">       <authorizType>registered</authorizType>     </securityManager>   </portlet> </provider>

Note the following:

• The authType tag in the provider.xml file above specifies that this provider will support single sign-on authentication against an external application. The login URL, username and password will be retrieved from the Login Server according to the mapping that is set up between the provider and the external application upon provider registration. 

• The pageUrl tag for the showPage of the portlet refers to the finance.yahoo.com URL for your login.  In this case, the URL was http://finance.yahoo.com/p?v&k=pf_2, but in the XML file, we must escape the "&" character with "&".  So the URL in the XML file appears as http://finance.yahoo.com/p?v&k=pf_2.

• The pageUrl tag for the editPage refers to the customize page of the finance portfolio.  In our case, this is http://edit.finance.dcx.yahoo.com/e0?u.

• The pageUrl tag for the helpPage refers to the help page for Yahoo! Finance.  In our case, this is http://help.yahoo.com/help/fin/.

• There are two optional filter tags in the renderer section.  These tags are for removing contents from the header and footer section of the output page before rendering the page as a portlet.  Note that the "<" character must be replaced with "&lt;" and the ">" character must be replaced with "&gt;".  The headerTrimTag trims all contents of the HTML header before the first occurrence of the value specified.  The footerTrimTag trims all contents of the HTML header after the first occurrence of the value specified.  To use headerTrimTag and footerTrimTag effectively, first open the page whose contents you are trying to access, then decide the region of contents you want.

Understanding the External Application Provider

To build a portlet from a secured external application such as My Yahoo!, you must first create an external application in the Login Server to store "portal user"-to-"external application user" mappings.  Creating an external application in the Login Server enables your portlet to perform single sign-on on behalf of the portal user.  The following screen is used to create an external application in the Login Server:

Upon creating the external application, you should enter your credentials for that application at the appropriate screen.

Once your credentials have been entered, the Login Server will know how to map your portal user to the corresponding user of the external application.  At this point, you are ready to register the portlet provider corresponding to the external application you've just created.  Registering the portlet provider involves following the same steps as registering a normal web provider, except in this case, since you're provider is retrieving content from a secured external application, you must specify the mapping between the provider and the appropriate external application (the one you just created).

Once your provider has been successfully registered, you can add your portlet to a page to see content from your secured external application.