# OracleAS Portal Developer Kit (PDK)
Configuring the Web Clipping Provider

Last Updated: | September 15, 2003
Status: | Production
Version: | PDK Release 2 (9.0.4.0.2 and later)

### Contents

> Introduction
> Web Clipping Provider Dependencies
> Web Clipping Provider Test Page
> Registering the Web Clipping Provider
> Troubleshooting

## Introduction

Before you can configure the Web Clipping Provider, you must install the PDK-Portal Tools. The installation instructions are located in the installing.portaltools.html document, which can be found under the pdk/portalTools directory when you unzip pdk.zip.

This document describes how to configure the Web Clipping Web provider that is included in the PDK-Portal Tools download.

The Web Clipping Web Provider is a Portlet Provider for Oracle Application Server Portal. The Web Clipping Portlet enables Page Designers to collect existing Web content into centralized Portal pages as a means of content consolidation. Within a corporate intranet, various Web sites may serve different vertical purposes. United into a Portal Page these vertical information sources take on new meanings in the ways that they are applied.

### Changes

With PDK 9.0.4.0.2 marks some major functionality improvements for the Web Clipping Provider. They were added as a first step in replacing URL-based Portlets' functionality. The notable new features include:

#### New Features

- External Application Integration
- In-line Rendering
- URL-based Portlets Migration

#### Deprecated Features

There was a feature whereby a Page Designer can enable or disable an instance of the Web Clipping Portlet to allow Page Viewers to modify the clipping - not just the customizations, by Page Viewers. This has been a source of confusion among users and does not provide sufficient value-add for us to continue on with it.

### Features

The Web Clipping Provider is further described by the list of features it supports.

#### Web Clipping Studio

- Web-based: Web-based tool to create Web Clippings
- Browse Mode: Browser-like navigation to target Web page
  - Browsing through links
  - Form Submissions (including Login)
  - HTTP Basic and Digest Authentication
  - JavaScript Support
  - Frames Support
- Section Mode: Section target Web page into Selectable Clippings
  - Zoom In: Increases granularity of the sectioning
  - Zoom Out: Decreases granularity of the sectioning
- Preview Mode: Preview your Clipping in isolation before completing creation

#### Portlet Show Mode

- Display Web Clipping as content of the portlet
- Automatic Login if necessary
- Maintain session if logged in

#### Fuzzy Match

When the Web Clipping has moved within its page, it will be re-discovered by the Web Clipping engine using Fuzzy Matching technologies.

#### Customizable

A page designer can make a Web Clipping customizable, exposing input parameters that Page Viewers can modify when they customize the Portlet. Starting in PDK 9.0.4.0.2, these parameters are mapped to Portlet parameters that the Page Designer can further map to Page Parameters.

#### Caching

The Web Clipping Provider supports both invalidation-based and validation- based caching. As network bandwidth to external sites may be a limited resource, caching allows for minimizing the round trips that the provider has to make to the external sites.

#### Timeout

It may take too long to connect to sites you want to clip, thereby hindering the loading of other Portlets on the same page. The timeout feature allows the Clipping to give up trying to connect if a specified time limit is exceeded.

#### Security

Sensitive information such as passwords are securely encrypted in a Web Clipping Repository using Oracle Security technologies. Customers with the Advanced Security Option (ASO) in their Oracle9i database (Enterprise Edition), can configure the provider to encrypt and secure the channel between the Web Clipping Provider and the database hosting the Web Clipping Repository.

#### Internationalization

Enables users to clip sites with different character encodings, and return their content uniformly as UTF-8 back to OracleAS Portal.

#### External Application Integration

Starting with PDK 9.0.4.0.2, the Web Clipping Provider has been integrated with the External Application framework to allow for a more automated mechanism to store passwords to external web sites. All you have to do additionally is to associate an External Application ID to the Web Clipping Provider during registration time.

#### In-line Rendering

Starting with PDK 9.0.4.0.2, the Web Clipping Provider will allow the user to have all the links within the Web Clipping Portlet rewritten so that when the user browses within the portlet it never leaves Portal. In contrast, earlier versions bring the user out of Portal into whatever external web site is providing the clip. With in-line rendering, users can now internalize external web sites into Portal the same way they did with URL-based portlets.

#### URL-based Portlets Migration

Starting with PDK 9.0.4.0.2, the Web Clipping Provider provides a mechanism for users to migrate their existing URL-based portlets, into Web Clipping portlets. As URL-based portlets are slated for deprecation, we strongly urge customers of these portlets to start the migration process. The instructions on how to perform the migration is documented in migrating.urlservices.to.webclipping.html (located under the pdk/articles directory)

## Web Clipping Provider Dependencies

The OracleAS components shown in the table below are required for the Web Clipping Provider to function properly. These are installed as part of the OracleAS installation. For more information, see installing.portaltools.html (located under the pdk/portalTools directory when you unzip pdk.zip).

Component | Description | Required? | Degradation Policy if Not Installed or Configured
Oracle9i DB Standard or Enterprise Edition | Required for persistent storage of Web Clipping Definitions | Yes | Web Clipping Portlet will not work in the absence of a database. The test page guides the user through the steps of setting up the necessary information for connecting to the the Oracle9i database that will host the Web Clipping Repository.
Web Cache | Required for invalidation based caching of Web Clipping portlet content | No | Portlet can use validation-based caching instead if Web Cache is not configured.
Advanced Security Option (ASO) | Database dependency on setting up secure connections to the Web Clipping Repository | No | This option can be configured from the test Page. If ASO is configured to be "on" for the Web Clipping Provider, but the database does not have the corresponding setup for ASO, connections will revert to not use ASO while warnings will be logged for the administrator.

You can configure all of the above components using the Web Clipping Provider test page.

## Web Clipping Provider Test Page

The Web Clipping Provider Test Page gives you an indication of whether the provider is functioning properly. You can access this Test Page by clicking the Web Clipping Provider link from the Portal Tools Application Welcome Page (http://<server>:<host>/portalTools). The Test Page displays:

- Portlet Information
  - Web Clipping Portlet (the Web Clipping Provider contains only one portlet)
- Provider Initialization parameters and values
- The status of each of the above, with links to configuration instructions.

### Required Configuration

The following is the required configuration for the Web Clipping Provider to function properly:

- Web Clipping Repository

  Web Clippings have definitions that need to be stored persistently in a Web Clipping Repository hosted by an Oracle9i database. The Web Clipping Provider Test Page will first automatically detect whether the Web Clipping Provider is configured to access the database. If not, it will display an Edit link next to the status of the Web Clipping Repository. This enables you to (re)configure the database connection parameters in the Edit Provider Page.

  If this is the first time you are installing the Web Clipping Provider, you will need to request a database user account from your Oracle9i database administrator before you begin configuring. The following SQL*Plus snippet can be used by your DBA to create the user:

  `CREATE USER <username> IDENTIFIED BY <password> ;
  GRANT connect, restricted session, resource TO <username> ;`

  To configure the repository settings:

1. Click the Edit link on the Web Clipping Provider Test Page next to the status of the Web Clipping Repository. The Edit Provider page displays.
2. In the Repository Settings section on this page, start by selecting the appropriate Repository Target. There are two options that you can select: "OracleAS Infrastructure Database" and "Other Oracle9i (or later) Database". Review the following notes before selecting one.
   - OracleAS Infrastructure Database:
     As a trusted application in an OracleAS middle tier, the Web Clipping Provider has the privilege to access the Infrastructure database associated with that OracleAS instance. This option does not require the Administrator to know the details of the connection information and is more convenient when the Web Clipping Provider is installed as part of an OracleAS middle tier install, or from a PDK install on top of an existing OracleAS middle tier. This is the default option.
   - Other Oracle9i (or later):
     If the Web Clipping Provider is not part of an OracleAS middle tier install, the only viable Repository Target is most often "Other Oracle9i (or later) Database". With this option, enter valid values for the Database:
     - Server Host,
     - Listener Port,
     - SID,
     - Username, and
     - Password.
     These must be set to valid values in order for the Web Clipping Provider to access the database that would be hosting the Web Clipping Repository.
   Interoperability Note: If you pair up an OracleAS 9.0.4 middle tier with an Oracle9iAS 9.0.2 Infrastructure database, since by default the Infrastructure Database will be chosen as the Repository Target, it will be pointing to your 9.0.2 Infrastructure database, which does not contain the tables necessary for the Web Clipping Repository. Therefore, you will need to visit the Web Clipping Provider test page and click "Install" to install the necessary tables into the 9.0.2 Infrastructure database (see below).
3. Click OK or Apply to save your changes. Once configured, you will be returned to the test page.

4. Each time you visit the Test Page, a check will be performed to ensure that you are able to connect to a database hosting the Web Clipping Repository. If successful, the Test Page next determines whether the correct database tables are present in the specified schema. If so, the Test Page reports that the Web Clipping is ready to use. Otherwise, an Install link displays next to the status of the Web Clipping Repository on the Test Page. You can click it to dynamically install the required schema tables into the user's schema that you provided earlier.

5. If you have specified for your Repository Target the same database as the one previously used for a PDK 9.0.2.4.0 installation, as part of your PDK upgrade, you will be notified that a Repository Upgrade also needs to take place. Upon entering the Web Clipping Provider Test Page, you will see an Upgrade (from 9.0.2.4.0) link that allows you to do a one-click upgrade for installing new tables as well as migrating existing Clipping Definitions to the latest versions.
   Note: After the upgrade, the Clipping Definitions stored in the Web Clipping Repository will no longer work with PDK 9.0.2.4.0.

### Optional Configuration

The following are the optional configurations for the Web Clipping Provider. If not available, the provider will degrade gracefully, or a specific functionality may become unavailable. On the Web Clipping Provider Test Page, click the links in the Action column next to a Setting to configure it.

#### HTTP Proxy Information

If a proxy server is required for the provider to make HTTP connections to an HTTP server outside the firewall, you must set up the HTTP proxy information. To do this, click Edit next to the status of the HTTP Proxy on the Web Clipping Provider Test Page. The Edit Provider page displays, on which you can specify the HTTP Proxy Host and the HTTP Proxy Port for the HTTP Proxy. For access to servers that are inside the firewall, you can specify a list of domain names that will not require going through the firewall with the field No Proxy for Domains beginning with. You do not need to restart OC4J for the new settings to take effect. Click the Help link to get more information.

#### Web Cache

If you want your portlet content cached using invalidation-based caching, an Oracle Web Cache instance must be configured in front of your provider. For more information on how to set this up, see Setting up the Invalidation Caching Sample.

After you set up and start the Web Cache instance, register the Web Clipping Provider as usual, but set the URL host name and port number to point to the Web Cache instance instead. For example,

http://<cache_instance_name>:<cache_port>/portalTools/webClipping/providers/webClipping

When a Web Clipping portlet definition is altered either though an Edit Defaults or Customize page, the provider generates a request that invalidates and removes the portlet content from the cache. The invalidation request is sent to the invalidation port of the Web Cache instance.

The invalidation port is defined by the cache.xml configuration file (a template copy can be found under pdk/portalTools/conf/portal/conf directory). To specify the port, modify the configuration file as indicated by italicized entries shown in the following example:

          <?xml version="1.0"?>
          <webcache>
            <invalidation
              host="cache.us.oracle.com"
              port="4001"
              authorization="invalidator:invalidator"/>
          </webcache>

The provider locates the cache.xml file using one of the following methods:

- First, it looks in $IAS_HOME/portal/conf/cache.xml.
  - The $IAS_HOME is derived as follows:
    - Checking the system property oracle.home
    - If not set, it is derived from the relative position of the portal/jlib/wce.jar file.
- If that file is not found, it looks in the default location as defined by the system property oracle.http.configfile.

If the Web Cache Invalidation setting is not configured properly, Web Cache will continue to return stale content that no longer reflects the portlet definition. To fix this, check the application.log file for these errors (refer to the Troubleshooting section below for its location):

- Error: CONFIGURATION: Provider Test Page: Web Cache component not installed properly.
  java.lang.NoClassDefFoundError: oracle/webcache/invalidation/invalidators/InvalidatorElement
  - Reason: webcache/jlib/jawc.jar is not installed.
- Error: CONFIGURATION: Provider Test Page: Web Cache Invalidation config file not defined by "oracle.http.configfile"
  - Reason: The "oracle.http.configfile" system property is not defined when you start OC4J.
- Error: CONFIGURATION: Provider Test Page: Web Cache Invalidation config file defined by "oracle.http.configfile" does not exist.
  - Reason: The configuration file defined by "oracle.http.configfile" system property does not exist.

See the Troubleshooting section below for the location of the application.log file. For additional Web Cache troubleshooting tips, see Setting up the Invalidation Caching Sample.

#### Advanced Security Option

The Web Clipping Provider can use Oracle Advanced Security Option (ASO) to secure and encrypt the channel between itself (at the Middle-Tier) and the database which hosts the Web Clipping Repository. Because ASO is a feature available only on Oracle9i DB Enterprise Edition, or as an add-on option to the Standard Edition, this feature is not turned on by default. To turn it on, you can go to the Edit Provider page from the Test Page, by clicking on the Edit link next to the status of the Web Clipping Repository. Then while editing the Repository Settings, enable ASO.

Note: When a change like this happens after the initial configuration (where the database parameters are already set up), the database connections are assumed to be already open. Since enabling ASO affects all connections made to the database, it is advisable to restart the OC4J instance containing the Web Clipping Provider to reset all the current connections to now use ASO. The same logic applies for the opposite direction.

#### Library For HTTPS Access in Standalone OC4J Installation

The Web Clipping Provider can access data through HTTPS URLs. To access these URLs, the Web Clipping Provider needs access to njssl9.dll (for Windows®) or libnjssl9.so (for Unix). For providers running on Windows®, njssl9.dll must be present in a folder defined in the PATH environment variable. For Unix systems, libnjssl9.so file must be found in the folder defined in LD_LIBRARY_PATH environment variable.

You can typically find this library and copy it from the $IAS_HOME/bin directory in an OracleAS installation. After copying, you must restart OC4J.

## Registering the Web Clipping Provider

After everything is configured correctly for the Web Clipping Provider, you will need to register the Web Clipping Provider as a Portlet Provider into your instance of Portal in the same way you normally register Providers.

Fill out the provider information for the Web Clipping Provider:

Name | webClipping
Display Name | Web Clipping Provider
Timeout | Specify something realistic based on your understanding of how you are connected to the Web sites you want to clip. If they are all within your corporate firewall, you can set a small value like 30 seconds, otherwise, a 60 or 90 seconds timeout will most likely be sufficient.
Implementation | Web
URL | http://{server}:{port}/portalTools/webClipping/providers/webClipping
User's Identity | For generic use of the Web Clipping Portlet, select the radio button with "The user has the same identity in the Web providers application as in the Single Sign-On identity." For use with an External Application so that login to external web sites can be automated through SSO, select the radio button with "The user's identity needs to be mapped to a different name in the Web provider's application, and/or the Web provider requires an external application login for establishment of a browser session. If selecting this option, specify the external application ID below."
External Application ID | If it has been specified above that the user's identity needs to be mapped, you must provide an External Application ID by clicking the LOV and selecting the ID of an external application you wish the Web Clipping Provider to be logged into. Note: In the creation of the External Application, you must specify an extra parameter called redirectFieldName that will denote the name (not value) of the field that the external Web site understands to allow the Web Clipping Provider to specify where to be redirected to after logging in. To illustrate this with an example, go to http://my.oracle.com and do not login. Move the mouse over the "Click Here" and see the link in your browser's status bar. It says something like http://my.oracle.com/pls/moc/MOC.wwsec_app_priv.login?p_requested_url=/pls/moc/MOC.home so in the setup of your external applications, you would specify the "redirectFieldName" to be "p_requested_url".
User/Session Information | Select the radio button "User", to send user specific information to the Provider.
Login Frequency | Once per user session
Require Proxy | Depends on your deployment of your PDK versus your Oracle Portal instance

Click Finish.

Note: When registering a new provider with Oracle Portal, only the user who registered the provider has privileges to see the provider/portlets. If necessary, go to the Folder with the name of the provider within the Portlet Repository content area and update the provider privileges as required.

## Troubleshooting

You can view errors that occur when bringing up the Test Page:

- In the web server file, $OC4J_HOME/j2ee/home/application-deployments/portalTools/application.log, or $IAS_HOME/j2ee/<OC4J_instance>/application-deployments/portalTools/<OC4J_instance>_default_island_1/application.log

You can view errors that occur during the execution of the Web Clipping Portlet:

- In the web server file, $OC4J_HOME/j2ee/home/application-deployments/portalTools/application.log, or $IAS_HOME/j2ee/<OC4J_instance>/application-deployments/portalTools/<OC4J_instance>_default_island_1/application.log

Errors that can occur during Configuration of the Web Clipping Provider are listed as follows:

- Error: Web Clipping Provider failed in registering.
  - Reason: The portalTools.ear Application is probably not deployed correctly.
  - Action: Make sure that it is deployed per the installing.portaltools.html
- Error: I get a NullPointerException when I tried to save the Clipping using the "Select" button.

- Reason: You probably did not configure your Web Clipping Provider.
- Action: Go to the test page and configure it there.

- Error: I timeout when trying to go to any web site

- Reason: If you are behind a firewall, you will need to setup your proxy information.
- Action: Go to the Web Clipping Provider Test Page and follow the "Edit" link to configure your proxy.

- Error: My Web Clipping content never changes. What's wrong?
  - Reason: You probably registered the Web Clipping Provider using the Web Cache port but configured the Web Clipping Provider to use Portal's validation-based caching. As a result, Web Cache is not being told to invalidate your content.
  - Action: Either change the configuration of the Web Clipping Provider to use Web Cache (invalidation-based) or Edit your provider in Oracle Portal to change the port number in the Connections tab to point to the non-Web Cache port.
- Error: Web Clipping Provider Test Page Fails to Load
  - Reason: The portalTools.ear file was not deployed correctly or that the libraries that this page needs are not present.
  - Action: To verify that the portalTools.ear is deployed correctly, try to access the portalTools home page at http://<server>:<host>/portalTools/ and see if that loads. If not then re-deploy it using OEM and make sure that no errors occur when deploying.

Revision History: |
Revision No | Last Update
1.0 | October 21, 2002
2.0 | September 15, 2003

Oracle Corporation World Headquarters 500 Oracle Parkway Redwood Shores, CA 94065, USA http://www.oracle.com/ | Worldwide Inquiries: 1-800-ORACLE1 Fax 650.506.7200 | Copyright and Corporate Info