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

Last Updated: | August 8, 2003
Status: | Production
Version: | PDK Release 2, (9.0.2.6.2 and later)

### Contents

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

## Introduction

Note: Before you configure the Web Clipping Provider, you must install the PDK-Portal Tools. This is described in the installing.portaltools.html document, which can be found under the pdk/portalTools directory when you unzip pdk.zip.

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

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

#### 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 9i 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 Oracle Portal.

## 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 Oracle9 i 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 on 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 Oracle 9i database. The 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're installing the Web Clipping Provider, you'll need to request a database user account from your Oracle 9i database administrator before you begin configuring. The following SQLPlus 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, first start by selecting the appropriate Repository Target. Unless the Web Clipping Provider is installed as part of an OracleAS middle tier install where there is an available Infrastructure database, the only viable Repository Target is most often "Other Oracle9i (or later) Database". With this option enter valid values for the Database Server Host, Database 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 is hosting the Web Clipping repository.
3. Click OK or Apply to save your changes. Once configured, you will be returned to the test page where you came from.

4. Each time you visit the Test Page, a sanity 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 that you provided earlier.

5. If you have specified for your Repository Target the same database as the one used for a PDK 9.0.2.4.0 installation before, 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'll see a 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 in the Web Clipping Repository can 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 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 need to 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 on Help link there 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 Oracle 9i DB Enterpriese 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'll need to register the Web Clipping Provider as a Portlet Provider into your instance of Portal in the same way that you used to 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 | Select the radio button with "The user has the same identity in the Web providers application as in the Single Sign-On identity."
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/application-deployments/portalTools/application.log, or $IAS_HOME/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
3.0 | August 8, 2003
2.0 | June 2, 2003
1.0 | October 21, 2002

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