I Configuring the Portal Tools Providers

I.1.3.1 Configuring Proxy Settings Using the Web Clipping Test Page

As portal administrator, you can configure proxy settings using the Web Clipping Test page at:

http://<host>:<port>/portalTools/webClipping/providers/webClipping

To configure proxy settings using the test page:

1. In the Provider Configuration section, the Setting column contains the field HTTP Proxy. Click its corresponding Edit link in the Actions column.

2. In the Proxy Settings section of the Edit Provider: webClipping page, enter the proxy settings for the Web Clipping provider:

   • HTTP Proxy: Enter the name of a proxy server if one is required for the provider to access the Web site being clipped. A proxy server provides access to content from servers outside a firewall.

   • Port: Enter the port number for the HTTP Proxy server. If you specify an HTTP Proxy server, but not a port, the HTTP Proxy port is set to default port number 80.

   • No Proxy for: Enter the name of any domain to which you can directly connect, bypassing a proxy server. Domain names are the part of a URL that contain the names of a business, or organization, or government agency, for example:

     .company.com, .companycorp.com, .us.company.com
     
     

     You can also use this field to specify a list of host names to restrict content, as described in Section I.1.3.3.

   • Requires Authentication: Select this check box for proxy servers that require authentication before access. Then, enter information in the following fields:

     • Type: Choose the type of proxy server this provider will use: Basic or Digest.

     • Realm: Enter the name of the realm of the proxy server that will be accessed by the user. If you do not know the name of the realm, contact the administrator of the proxy server.

     • Login Scheme: Choose one of the following options:

       Use login below for all users: By choosing this option, the login information you enter in the Username or Password fields will be used for all users. Users will not see the Proxy Authentication section on the Edit Defaults and the Personalize pages.

       Require login for all users: By choosing this option, you do not enter any information in the Username or Password fields. Page designers must enter authentication information for the proxy server on the Edit Defaults page when they define the portlet. They only need to enter the information once for the Portlet instance. End users must enter authentication information for the proxy server on the Personalize page.

       Require login for all users - use login below for public users: By choosing this option, the login information you enter in the Username or Password fields will be used for all public users only. If the user is not public, they must enter authentication information for the proxy server on the Personalize page.

     • Username: Enter the user name to log in to the proxy server.

     • Password: Enter the password for the specified user name.

     If you select the Requires Authentication check box and require users to log in (that is, you choose either Require login for all users or Require login for all users - use login below for public users), you must configure the Web Clipping repository. To configure the repository, see Section I.1.1.

   Figure I-3 shows the Proxy Settings section of the Edit Provider page:

   Figure I-3 Web Clipping - Proxy Settings

   
   Description of "Figure I-3 Web Clipping - Proxy Settings"
   
   

3. Click OK to save the settings and return to the Web Clipping Test page.

I.1.3.2 Setting Proxy Settings Manually

As the portal administrator, you can set proxy settings manually according to your HTTP or HTTPS configuration. Edit the appropriate entries in the provider.xml file located in the following directory:

On UNIX:

ORACLE_HOME/j2ee/OC4J_Portal/applications/ portalTools/webClipping/WEB-INF/providers/webClipping

On Windows:

ORACLE_HOME\j2ee\OC4J_Portal\applications\ portalTools\webClipping\WEB-INF\providers\webClipping

The following example shows the relevant portion of provider.xml:

<proxyInfo class="oracle.portal.provider.v2.ProxyInformation">
<httpProxyHost>proxy_hostname</httpProxyHost>
<httpProxyPort>proxy_portnum</httpProxyPort>
<dontProxyFor>list_of_proxies</dontProxyFor>
<proxyUser>proxy_username</proxyUser>
<proxyPassword>proxy_password</proxyPassword>
<proxyType>basic_or_digest</proxyType>
<proxyUseAuth>true_or_false</proxyUseAuth>
<proxyUseGlobal>true_or_false</proxyUseGlobal>
<proxyRealm>realm_name</proxyRealm>
</proxyInfo>

The elements have the following meanings and values:

• httpProxyHost: The name of a proxy server if one is required to make a URL connection with the provider, for example, when OracleAS Portal requests one of the provider's portlets. A proxy server provides access to content from servers outside a firewall.

• httpProxyPort: The port number for the proxy server. If you specify an httpProxyHost, but not a port, httpProxyPort is set to default port number 80.

• dontProxyFor: The name of any domain to which you can directly connect, bypassing a proxy server. Domain names are the part of a URL that contain the names of a business, or organization, or government agency, for example:

  .company.com, .companycorp.com, .us.company.com
  
  

  You can also use this element to specify a list of host names to restrict content, as described in Section I.1.3.3.

• proxyUser: The user name to log in to the proxy server.

• proxyPassword: The password for the specified user name.

• proxyType: The type of proxy server this provider will use. Valid values are Basic or Digest.

• proxyUseAuth: Whether or not login information is required to access this proxy server. A value of true specifies that login information is required. A value of false indicates that login information is not required.

• proxyUseGlobal: Whether or not the user name and password are required for public users or all users and how the user name and password are used. This element is only relevant if proxyUseAuth is set to true.

  • If the value of proxyUseGlobal is true, the proxy_username specified in proxyUser and the proxy_password specified in proxyPassword are used for all users. The proxyUser and proxyPassword elements must be present in the file and must contain a user name and password. Users will not see the Proxy Authentication section on the Edit Defaults and Personalize pages.

  • If the value is false and the proxyUser and proxyPassword elements are present in the file, the specified proxy_username and proxy_password are used for public users only. If the user is not public, they must enter authentication information for the proxy server on the Personalize page.

  • If the value is false and the proxyUser and proxyPassword elements are not present in the file, all users must log in. Page designers must log in using the Proxy Authentication section on the Edit Defaults page when they define the portlet. End users must enter authentication information for the proxy server on the Personalize page.

  If the value is false, regardless of whether or not the proxyUser and proxyPassword elements are present in the file, you must configure the Web Clipping repository. To configure the repository, see Section I.1.1.

• proxyRealm: The name of the realm of the proxy server that will be accessed by the user. If you do not know the name of the realm, contact the administrator of the proxy server.

I.1.3.3 Restricting Users from Clipping Content from Unauthorized External Web Sites

To restrict users from clipping content from unauthorized external Web sites, Web Clipping uses the proxy exception list. This is available only for environments that utilize a proxy server to reach external Web sites. (Usually, you use the proxy exception list to specify any domain to which you can directly connect, bypassing a proxy server.)

To add an external Web site to the proxy exception list:

1. Go to the Edit Provider: webClipping page, as described in Section I.1.3.1.

2. In the Proxy Settings section, for the No proxy for field, enter the Web sites which you want to restrict.

3. Click OK to save the settings and return to the Web Clipping Test page.

Users attempting to reach a Web site in one of the listed domains, from the Web Clipping Studio, will receive an HTTP timeout error.

I.1.4.1 Configuring Caching Using the Web Clipping Test Page

As portal administrator, you can configure caching using the Web Clipping Test Page at:

http://<host>:<port>/portalTools/webClipping/providers/webClipping

To configure caching:

1. In the Provider Configuration section, the Setting column contains the field Portlet Caching. Click its corresponding Edit link in the Actions column.

2. In the Time out settings section of the Web Clipping Portlet page, enter the number of seconds OracleAS Portal should try to connect to Web Clipping portlets before displaying a timeout message.

3. In the Caching Parameters section, specify a cache expires value in the Cache Expires field. The default value is 30 minutes.

4. In the Caching Scheme field, select the caching scheme (either validation or invalidation (requires OracleAS Web Cache).)

   Figure I-5 shows the Web Clipping Portlet page:

   Figure I-5 Web Clipping Portlet Page

   
   Description of "Figure I-5 Web Clipping Portlet Page"
   
   

5. Click OK to save the settings and return to Web Clipping Test page.

I.1.4.2 Configuring Caching Manually

To manually enable caching with OracleAS Web Cache, take the following steps:

1. Check the cache.xml file in the following directory to verify the accurate values of the invalidation host and port number:

   On UNIX:

   ORACLE_HOME/portal/conf
   
   

   On Windows:

   ORACLE_HOME\portal\conf
   
   

2. Edit the provider.xml file located in the following directory:

   On UNIX:

   ORACLE_HOME/j2ee/OC4J_Portal/applications/
   portalTools/webClipping/WEB-INF/providers/webClipping
   
   

   On Windows:

   ORACLE_HOME\j2ee\OC4J_Portal\applications\
   portalTools\webClipping\WEB-INF\providers\webClipping
   
   

   In the provider.xml file:

   1. Search for the useInvalidationCaching tag and set its value to true to enable OracleAS Web Cache invalidation-based caching.

   2. Search for the cacheExpires tag and set a default value if you wish to modify that value. This value is in minutes.

I.2.1.1 Configuring HTTP or HTTPS Proxy Settings

If a proxy server is required for the provider to make a URL connection to a data source outside the firewall, then you must set up the HTTP or HTTPS Proxy.

If you have configured the proxy settings for Web Clipping provider already using the Web Clipping Test page, then you need not configure them again for the OmniPortlet provider. If you configured the proxy settings for the Web Clipping provider manually, that is by editing the Web Clipping provider.xml file, then you need to perform the same steps for the OmniPortlet provider by editing the OmniPortlet provider.xml file located in the following directory:

ORACLE_HOME/j2ee/OC4J_Portal/applications/portalTools/omniPortlet/WEB-INF/providers/omniPortlet

To configure the proxy settings, click Edit next to HTTP Proxy on the OmniPortlet Provider Test page. An Edit Provider page is displayed, on which you can specify the HTTP Proxy Host, Proxy Port, and other proxy information. For an installation where the proxy server access requires authentication, you can specify the user name and password at the following levels:

• Global: Login information is shared for all users. Specify the global login information in the Edit Provider page.

• For each user: Users must set their own login information on an OmniPortlet instance as follows:

  • For page viewers, set the login information in the Personalize page.

  • For page designers, in the Edit Defaults mode, click the Source tab, then set the login information.

You do not need to restart OC4J for the new settings to take effect. Refer to the Web Clipping provider section, Section I.1.3, "Configuring HTTP or HTTPS Proxy Settings" for more information about configuring proxy settings.

I.2.1.2 Configuring the Secured Data Repository (PDK only)

OmniPortlet uses the Web Clipping repository to store credentials needed to access secured data. You must configure the repository if you intend to use the Web Page data source or work with secured data (for example, a SQL database or a URL-based data source with HTTP basic authentication). If you have configured the Web Clipping Repository already, you do not need to configure the Secured Data Repository again because they are the same repository.

To configure the repository, click Edit next to Secured Data Repository on the OmniPortlet Provider Test page. The Edit Provider page is displayed, on which you can enter the repository information. Refer to the Web Clipping provider section, Section I.1.1, "Configuring the Web Clipping Repository" for more information.

I.2.1.3 Configuring Caching (PDK Only)

If you want the portlet content cached using invalidation-based caching, then an OracleAS Web Cache instance must be configured as a front end to the provider.

You must use the URL host name and port number to point to the OracleAS Web Cache instance when registering the provider as shown in the following example:

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

This task must be performed when registering the OmniPortlet provider. Refer to Section I.2.3, "Registering the OmniPortlet Provider (PDK Only)" for details about registering the OmniPortlet provider.

When an OmniPortlet definition is altered either through the Edit Defaults or Personalize 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 OracleAS Web Cache instance. Information about the OracleAS Web Cache instance is maintained in the cache.xml file in the ORACLE_HOME/portal/conf directory. If the Web Cache invalidation settings change, then you must update this file. The following example shows sample entries in the cache.xml file:

<?xml version="1.0"?>
<webcache>
    <invalidation
        host="<cache_instance_name>"
        port="<cache_invalidation_port>"
        authorization="<obfuscated_username_password>"/>
</webcache>

Where:

• <cache_instance_name> is the host name of the Web Cache instance.

• <cache_invalidation_port> is the Web Cache invalidation port.

• <obfuscated_username_password> is the invalidator user name and password.

  For information about obfuscating the invalidator user name and password, refer to the Oracle Application Server Portal Developer's Guide.

I.2.1.4 Configuring OmniPortlet to Access HTTPS URLs

You can configure OmniPortlet to access data through HTTPS URLs by doing the following:

• Adding Certificates for Trusted Sites

• Library For HTTPS Access (PDK Only)

Adding Certificates for Trusted Sites

Perform this task only once, either for Web Clipping or for OmniPortlet.

The trusted server certificate file, ca-bundle.crt, generated from Oracle Wallet Manager is shipped with OracleAS Portal. This file contains an initial list of trusted server certificates that may be used for navigating to some secure servers using HTTPS. However, because the file does not contain a complete list of all possible server certificates that exist on the Web, this file must be configured or extended to recognize any additional trusted server certificates for any new trusted sites that are visited. Refer to Section 6.1.9.1, "Adding Certificates for Trusted Sites" for details about configuring or extending the trusted certificate file.

Copying the Library for HTTPS Access (PDK Only)

To access HTTPS URLs, OmniPortlet needs access to the files, njssl10.dll (for Windows) or libnjssl10.so (for UNIX).

For providers running on Windows, the njssl10.dll file must be present in a folder defined in the PATH environment variable. If it is not available, then you can copy this library from the ORACLE_HOME/bin directory.

For providers running on UNIX, the libnjssl10.so file must be present in the folder defined in LD_LIBRARY_PATH environment variable. If it is not available, then you can copy this library from the ORACLE_HOME/lib directory.

After copying the library, you must restart the OC4J instance.

I.2.4.1 Installing DataDirect JDBC Drivers

DataDirect JDBC drivers are packaged in a single ZIP file containing the different drivers used to access supported databases. Download the ZIP file from the following location:

http://www.oracle.com/technology/software/products/ias/htdocs/utilsoft.html

To install DataDirect JDBC drivers, perform the following steps:

1. Unzip the contents of the ZIP file into a temporary directory, for example /temp/datadirect.

2. Create the ORACLE_HOME/j2ee/<OC4J_INSTANCE_HOME>/applib directory if it does not already exist.

3. From the /temp/datadirect/lib directory, copy the DataDirect JDBC drivers to the ORACLE_HOME/j2ee/<OC4J_INSTANCE_HOME>/applib directory.

4. Check the configuration of the OC4J_Portal instance to ensure that the DataDirect libraries are loaded. To do this, perform the following steps:

   1. Open the ORACLE_HOME/j2ee/<OC4J_INSTANCE_HOME>/config/application.xml file. This file is used to configure all applications in this instance.

   2. Add the XML entry, <library path="../applib"/>, to the file if it does not already exist.

I.2.4.2 Registering DataDirect Drivers in OmniPortlet

OmniPortlet is implemented as a Web provider and all the configuration properties are stored in the provider.xml file. To use DataDirect JDBC drivers with OmniPortlet, you must register these drivers in the provider.xml file.

To register the new DataDirect JDBC drivers, perform the following steps:

1. Back up the file, ORACLE_HOME/j2ee/<OC4J_INSTANCE_HOME>/applications/portalTools/omniPortlet/WEB-INF/providers/omniPortlet/provider.xml, and then open the file.

2. Add the drivers that you want to use for the SQL data source configuration entry. To do this, perform the following:

   1. Search for the XML tag, driverInfo.

   2. Add a new entry after the last driverInfo tag.

   Following is an example showing a Microsoft SQL Server entry:

   • For OmniPortlet version 9.0.4.1 or later:

     <!-- registration of DataDirect Connect for JDBC SQL Server driver -->
     <driverInfo class="oracle.webdb.reformlet.data.jdbc.JDBCDriverInfo">
       <name>Microsoft SQL Server</name>
       <sourceDataBase>other</sourceDataBase>
       <subProtocol>sqlserver</subProtocol>
       <connectString>mainProtocol:subProtocol://databaseName</connectString>
       <driverClassName>com.oracle.ias.jdbc.sqlserver.SQLServerDriver
       </driverClassName>
       <dataSourceClassName>com.oracle.ias.jdbcx.sqlserver.SQLServerDataSource
       </dataSourceClassName>
       <connHandlerClass>oracle.webdb.reformlet.data.jdbc.JDBCConnectionHandler
       </connHandlerClass>
       <connPoolSize>5</connPoolSize>
       <loginTimeOut>30</loginTimeOut>
     </driverInfo>
     
     

   • For OmniPortlet versions before 9.0.4.1:

     <!-- registration of DataDirect Connect for JDBC SQL Server driver -->
     <driverInfo class="oracle.webdb.reformlet.data.jdbc.JDBCDriverInfo">
       <name>Microsoft SQL Server</name>
       <sourceDataBase>other</sourceDataBase>
       <subProtocol>sqlserver</subProtocol>
       <connectString>mainProtocol:subProtocol://databaseName</connectString>
       <driverClassName>com.oracle.ias.jdbc.sqlserver.SQLServerDriver
       </driverClassName>
       <connHandlerClass>
       oracle.webdb.reformlet.data.jdbc.JDBCODBCConnectionHandler
       </connHandlerClass>
       <connPoolSize>5</connPoolSize>
       <loginTimeOut>30</loginTimeOut>
     </driverInfo>
     
     

   Table I-3 describes the parameters in the driverInfo property.

   Table I-3 Parameters in the driverInfo Property

   Parameter	Description
   name	Name of the database you want to use. This name will be used on the Source tab of the OmniPortlet wizard.
   sourceDataBase	Internal value. Set the value to other.
   subProtocol	JDBC subprotocol name used by OmniPortlet to create the connection string, for example sqlserver, sybase, or db2.To get the list of subprotocol names, refer to the DataDirect JDBC driver documentation using the links provided at the end of this section.
   connectString	Description of the connect string format. For DataDirect drivers, the format is: mainProtocol:subProtocol://databaseName
   driverClassName	Name of the driver class. To get the different values, refer to the DataDirect JDBC driver documentation using the links provided at the end of this section.
   dataSourceClassName	Name of the data source class that implements connection pooling. This parameter is only available in OmniPortlet version 9.0.4.1 or later. Refer to Table I-4 for the right data source class name for your driver.
   connHandlerClass	Class used by OmniPortlet to manage the driver and connection pooling. The value is either of the following: For OmniPortlet version 9.0.4.1 or later: oracle.webdb.reformlet.data.jdbc.JDBCConnectionHandler For OmniPortlet versions before 9.0.4.1: oracle.webdb.reformlet.data.jdbc.JDBCODBCConnectionHandler
   connPoolSize	Minimum number of connections that are opened by the connection pool.
   loginTimeOut	Maximum time, in seconds, that this data source will wait while attempting to connect to a database.

   
   

   Table I-4 lists the values for the driverClassName and dataSourceClassName properties for specific DataDirect JDBC drivers.

   Table I-4 Parameters and Values for driverClassName and dataSourceClassName

   DataDirect Drivers Supported	Properties
   Microsoft SQL Server	Parameter: driverClassName Value: com.oracle.ias.jdbc.sqlserver.SQLServerDriver Parameter: dataSourceClassName Value: com.oracle.ias.jdbcx.sqlserver.SQLServerDataSource
   Sybase	Parameter: driverClassName Value: com.oracle.ias.jdbc.sybase.SybaseDriver Parameter: dataSourceClassName Value: com.oracle.ias.jdbcx.sybase.SybaseDataSource
   DB2	Parameter: driverClassName Value: com.oracle.ias.jdbc.db2.DB2Driver Parameter: dataSourceClassName Value: com.oracle.ias.jdbcx.db2.DB2DataSource
   Informix	Parameter: driverClassName Value: com.oracle.ias.jdbc.informix.InformixDriver Parameter: dataSourceClassName Value: com.oracle.ias.jdbcx.informix.InformixDataSource

   
   

3. Save the provider.xml file.

4. Stop and start the Oracle Application Server instance.

Troubleshooting Information

If you encounter errors or problems when configuring or using the OmniPortlet provider, refer to Appendix K, "Troubleshooting OracleAS Portal" for troubleshooting information.