64 Creating Content-Based Portlets with Web Clipping

Web Clipping is a publishing portlet that enables you to integrate any web application with your WebCenter Portal: Framework application. Web Clipping is designed to give you quick integration by leveraging the existing user interface of a web application. With Web Clipping, you can collect web content into portlets in a single centralized web page. You can use Web Clipping to consolidate content from web sites scattered throughout a large organization.

This chapter includes the information you are required to know to use Web Clipping in your Oracle JDeveloper environment. For information about how to use Web Clipping at runtime, see the "Working with the Web Clipping Portlet" chapter in the Oracle Fusion Middleware User's Guide for Oracle WebCenter Portal: Spaces.

This chapter includes the following sections:

For information about the different types of portlets, producers, and other portlet technologies, see Chapter 57, "Introduction to Portlets."

Note:

The Web Clipping portlet is deprecated in Release 11g (11.1.1.7.0). Consider using a clipper pagelet using Oracle WebCenter Portal's Pagelet Producer. For more information, see the "Managing Oracle WebCenter Portal's Pagelet Producer" chapter in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

64.1 Introduction to Web Clipping

With Web Clipping you can clip an entire web page or a portion of it and reuse it as a portlet. You can clip basic and HTML-form-based sites. Use Web Clipping when you want to copy content from an existing web page and expose it in your Framework application as a portlet.

Web Clipping supports the following features:

  • Navigation through various styles of login mechanisms

    Web Clipping supports various login mechanisms including form- and JavaScript-based submission and HTTP Basic and Digest Authentication with cookie-based session management.

  • Fuzzy matching of clippings

    Fuzzy matching enables the Web Clipping engine to correctly identify a web clipping and deliver it as portlet content even if the web clipping is reordered within the source page or if its character font, size, or style changes.

  • Personalization

    Personalization enables you to expose input parameters that end users can modify when they personalize the portlet. Parameters can be exposed as public parameters that you can map as page parameters. This feature enables end users to obtain personalized clippings.

  • Integrated authenticated web content through single sign-on

    You can use external applications and leverage Oracle Single Sign-On to clip content from authenticated external web sites.

  • Inline rendering

    Inline rendering enables you to set up Web Clipping portlets to display links within the context of the portlet. When a user clicks a link in the Web Clipping portlet, the results display within the same portlet. You can use this feature with internal and external web sites.

  • Proxy authentication

    Web Clipping supports proxy authentication, including global proxy authentication and authentication for each user. You can use this feature if proxy servers require authentication. You can specify proxy server authentication details, including type (Basic or Digest) and realm in the provider.xml file. In addition, you can specify a scheme for entering user credentials:

    • All users automatically log in using a user name and password that you provide.

    • All users are required to log in using a user name and password that they provide.

    • All public users (not authenticated into the Framework application) automatically log in using a user name and password that you provide, while valid users (authenticated into the Framework application) log in using a user name and password that they provide.

    For more information, see Section 64.5.2, "HTTP or HTTPS Proxy Configuration."

  • Support for HTTPS

    Web Clipping enables you to clip content from HTTPS-based external web sites if appropriate server certificates are acquired. For information about server certificates, see Section 64.5.3.1, "Adding Certificates for Trusted Sites."

  • Open Transport API

    By default, the Web Clipping provider supports only HTTP challenge-based authentication methods, such as Basic and Digest and form submission logins. To support custom authentication methods, such as Kerberos proxy authentication, you can use the Web Clipping Transport API. For more information, see Section 64.4.1, "Using the Web Clipping Transport API."

  • Reuse of a wide range of web content

    Web Clipping provides basic support of pages written with JavaScript, applets, and plug-in enabled content, retrieved through HTTP GET and POST methods of form submission.

    Web Clipping also supports clipping of content from pages written with HTML 4.01, including:

    • Clipping of <applet>, <body>, <div>, <embed>, <img>, <object>, <ol>, <span>, <table>, and <ul> tagged content

    • Preservation of <head> styles and fonts, and CSS

    • Support for UTF-8 compliant character sets

    • Navigation through hyperlinks (HTTP GET), form submissions (HTTP POST), frames, and URL redirection

  • Globalization support

    Web Clipping provides globalization support in URLs and URL parameters. For information about how Web Clipping determines the character set of clipped content, see Section 64.6, "Current Limitations of Web Clipping."

  • Persistent storage of Web Clipping definitions

    Web Clipping definitions are stored persistently in a repository. By default, in JDeveloper, the Web Clipping producer is configured to use the file-based Oracle Metadata Service (MDS) as a repository. If you prefer, you can use a database schema for your Web Clipping repository. For information about configuring a Web Clipping repository, see Section 64.5.1, "Web Clipping Repository Configuration."

  • Encryption of secure information

    Any secure information, such as passwords, is stored in an encrypted form, according to the Data Encryption Standard (DES), using Oracle encryption technology.

64.2 Adding Web Clipping to Your Application

You can add a Web Clipping portlet to a JSP document created through JDeveloper. The Web Clipping portlet producer is included in:

  • Integrated WebLogic Server (WLS), the default server installed with JDeveloper

  • The WLS_Portlets managed server in the default domain in a full Oracle Fusion Middleware installation

To add a Web Clipping portlet to your application:

  1. In JDeveloper, start Integrated WLS. For information, see Section 3.4, "Working with the Integrated WebLogic Server."

  2. In JDeveloper, register the Web Clipping producer. For more information, see Section 62.3, "Registering an Oracle PDK-Java Portlet Producer with a WebCenter Portal: Framework Application."

    During this step, you must provide the endpoint URL, for example:

    http://localhost:7101/portalTools/webClipping/providers/webClipping

    You can choose to register the Web Clipping portlet producer from the WLS_Portlets managed server or Integrated WLS.

    When the producer is registered, portlets become available either in the Application Resources panel or the Resource Palette.

  3. From the Application Resources panel or the Resource Palette, drag the Web Clipping portlet onto your .jspx page. For more information, see Section 62.6, "Adding Portlets to a Page."

    If you are using a PanelCustomizable or ShowDetailFrame component, then drag the portlet on top of that component instead of af:form. In the Structure pane, the Web Clipping portlet must display under the PanelCustomizable or ShowDetailFrame component. In the Page Editor, the portlet must display inside the PanelCustomizable or ShowDetailFrame component.

    Note:

    When you add an instance of Web Clipping to your page in JDeveloper, open the Property Inspector for the portlet and ensure that the AllModesSharedScreen and RenderPortletInIFrame properties are set as follows:

    • AllModesSharedScreen is set to false to display the Customize and Personalize in full page size. If you do not set this property to false, then when you edit the Web Clipping portlet at runtime, the text displayed on the page may be distorted.

    • RenderPortletInIFrame is set to true to display the Web Clipping in its own inline frame (IFRAME) in the View mode.

  4. Right-click the .jspx page and choose Run.

    The Web Clipping portlet displays in your default browser.

  5. Customize the Web Clipping portlet to define its contents. For more information, see the "Working with the Web Clipping Portlet" chapter in the Oracle Fusion Middleware User's Guide for Oracle WebCenter Portal: Spaces.

    Note:

    To clip SSL-enabled web sites, you must add certificates of those sites to the certificate store. You are not required to add certificates of SSL-enabled web sites that use Equifax, VeriSign, or Cybertrust certificates because these certificates are included in the default certificate store.

    For information about adding certificates, see Section 64.5.3.1, "Adding Certificates for Trusted Sites."

64.3 Integrating Authenticated Web Content Using Single Sign-On

You can leverage Oracle Single Sign-On to integrate content from external web sites that require authentication, into a Web Clipping portlet.

Note:

You can associate only one external application with a producer. For each external application, you must register a new producer. Framework application users access the authenticated content by using their user name and password for that system, not your credentials.

To integrate an external application that requires authentication:

  1. Open your Framework application in JDeveloper.

  2. Register the external application, specifying the authentication information. For more information, see Section 68.13.3.2.1, "Registering an External Application in Oracle JDeveloper."

  3. Register the Web Clipping producer. For information, see Section 62.3, "Registering an Oracle PDK-Java Portlet Producer with a WebCenter Portal: Framework Application."

    While registering the producer by using the Register Oracle PDK-Java Portlet Producer wizard, on the Specify Connection Details page, select the Associate Producer with External Application checkbox, and from the list of values, select the external application that you just registered. The Enable Producer Sessions checkbox gets selected automatically.

    Figure 64-1 shows the external application named MyOracleSupport associated with a Web Clipping producer.

    Figure 64-1 Associating a Web Clipping Producer with an External Application

    Description of Figure 64-1 follows
    Description of "Figure 64-1 Associating a Web Clipping Producer with an External Application"

  4. Add the Web Clipping portlet from the producer that you just registered to a .jspx page.

  5. Right-click the .jspx page and choose Run.

  6. If you did not specify shared or public credentials for the external application, then the portlet contains an Update login information link. Click this link.

  7. Enter your credentials, and then click OK to log in to the external web site.

    Figure 64-2 shows the login screen of an external application named MyOracleSupport.

    Figure 64-2 Logging into the Integrated External Application

    Description of Figure 64-2 follows
    Description of "Figure 64-2 Logging into the Integrated External Application"

  8. Click the Actions icon on the header of the Web Clipping portlet, and select Customize.

    The Find a Web Clipping page displays, with the default URL for the external application displayed in the URL Location field (Figure 64-3).

    Figure 64-3 Finding a Web Clipping

    Description of Figure 64-3 follows
    Description of "Figure 64-3 Finding a Web Clipping"

    You can now select any section of a web page that you intend to display in your Web Clipping portlet. For information about how to customize a Web Clipping portlet, see the "Working with the Web Clipping Portlet" chapter in the Oracle Fusion Middleware User's Guide for Oracle WebCenter Portal: Spaces.

    After you clip the required page of the external application, the web clipping, even though it is from a page requiring authentication, is available in your portlet.

64.4 Advanced Features of Web Clipping

Web Clipping supports certain advanced features. You can configure custom authentication methods by using the Web Clipping Transport API and rewrite image links to use a resource proxy.

This section includes the following subsections:

64.4.1 Using the Web Clipping Transport API

To support custom authentication methods, you can use the Web Clipping Transport API. To extend the Web Clipping transport layer to support custom authentication methods, you must perform several implementation and deployment procedures.

This section includes the following subsections:

64.4.1.1 Implementing the Web Clipping Transport API

If you want to support a custom authentication method, such as Kerberos, you must first implement your own transport classes.

To implement custom transport classes:

  1. Override two use cases of the oracle.portal.wcs.transport.http.HttpTransportLiaison interface.

    In Web Clipping, this interface is used to abstract the HTTP transport layer. By default, the two use cases of this interface are manifested by the following implementations:

    • HttpClientStudioTransportLiaison, which handles HTTP transport in Web Clipping Studio mode

    • HttpClientProviderTransportLiaison, which handles HTTP transport in Web Clipping Producer show mode

    To support more authentication methods, you must override the addRequestHeaders methods for both the Studio and Provider HttpClientTransportLiaison implementations to add your own authentication-specific headers. For more information, see the Oracle WebLogic Server Web Clipping Transport API Reference.

  2. Compile the new subclasses and package them into a JAR file.

    For example, to compile the new subclasses, use the following command:

    javac -classpath path_to_wcejar -d classes/

    Where, path_to_wcejar refers to the path to the wce.jar file.

    To create the JAR file, for example, run the following command from the classes directory:

    jar cvf ../mytransport.jar

    Where, mytransport.jar refers to the JAR file users want to create.

64.4.1.2 Deploying the Web Clipping Transport API

After implementing the new transport classes, you must deploy the JAR file to support the custom authentication method.

To deploy the JAR file:

  1. Place the JAR file into the class path or shared library that is used by the Web Clipping producer at runtime.

  2. Register the transport class in the web.xml file for the Web Clipping producer by making the following modifications to the context parameters defined for HttpClientProviderTransportLiaison and HttpClientStudioTransportLiaison:

    • Change the parameter value for oracle.webclipping.provider.TransportLiaisonClass to the name of the new class extended from the HttpClientProviderTransportLiaison class.

    • Change the parameter value for oracle.webclipping.studio.TransportLiaisonClass to the name of the new class extended from the HttpClientStudioTransportLiaison class.

  3. Restart the producer server for the changes to take effect.

64.4.2 Rewriting Image Links to Use a Resource Proxy

Web Clipping enables you to rewrite image links to use a resource proxy. To enable this feature, you must add the following entry to the web.xml file of the Web Clipping producer:

<env-entry>
    <env-entry-name>oracle/webclipping/rewriteImageLink</env-entry-name>
    <env-entry-type>java.lang.Boolean</env-entry-type>
    <env-entry-value>false</env-entry-value>
</env-entry>

64.5 Web Clipping Portlet Configuration Tips

Before you use Web Clipping, you must perform some administrative tasks, including the following:

64.5.1 Web Clipping Repository Configuration

Web clippings have definitions that must be stored persistently in an Oracle Metadata Services (MDS) store or an Oracle database.

Note:

You cannot use a Microsoft SQL Server or IBM DB2 database as the Web Clipping repository.

You can view the Web Clipping repository configuration by accessing the Web Clipping Producer Test Page at:

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

Where, host is the server to which your Web Clipping producer has been deployed and port is the port to which the server is listening for HTTP requests.

Note:

Integrated WLS and the WLS_Portlet managed server are deployed to different ports even if they may be available on the same system. By default, Integrated WLS is deployed to port 7101 and WLS_Portlet is deployed to port 8889.

The Provider Test Page automatically detects whether the Web Clipping producer is configured with a valid repository. If it is not, then the Status column for the Web Clipping Repository displays Not Configured. Figure 64-4 shows the Provider Test Page of Web Clipping.

Figure 64-4 Web Clipping - Provider Test Page

Description of Figure 64-4 follows
Description of "Figure 64-4 Web Clipping - Provider Test Page"

You cannot change the Web Clipping configuration information by using the Provider Test Page. You can configure the Web Clipping repository by setting appropriate values in the provider.xml file. In this file, you use the repositoryInfo tag to specify the Web Clipping repository settings.

Note:

To determine the path of provider.xml, search for webClipping/provider.xml in the file system. For example, run the following command in UNIX:

> find DOMAIN_DIR -name "provider.xml" | grep -i webClipping

In Oracle JDeveloper's Integrated WLS, Web Clipping's provider.xml is located here:

JDEV_SYSTEM_DIRECTORY/DefaultDomain/servers/DefaultServer/tmp/_WL_user/portalTools_11.1.1.2.0/RANDOMLY_GENERATED_DIRECTORY/war/WEB-INF/providers/webClipping/provider.xml

Note that, on a Windows platform, pages in Framework applications are not rendered if there is a space in the path to the system directory in JDeveloper. Therefore, ensure that the JDEV_SYSTEM_DIRECTORY path does not contain spaces.

In the Fusion Middleware 11g installation, Web Clipping's provider.xml is located here:

FMW_HOME/user_projects/domains/wc_domain/servers/WLS_Portlet/tmp/_WL_user/portalTools_11.1.1.2.0/RANDOMLY_GENERATED_DIRECTORY/war/WEB-INF/providers/webClipping/provider.xml

This section includes the following subsections:

64.5.1.1 Using Oracle Metadata Services (MDS) as the Web Clipping Repository

By default, in Oracle JDeveloper, the Web Clipping producer hosted on Integrated WLS, the default server, is configured to use MDS, which is file-based, as the Web Clipping repository.

Note:

In a full Oracle Fusion Middleware installation, the Web Clipping portlet producer is also included within the WLS_Portlets managed server in the default domain. By default, this Web Clipping portlet producer is configured to use the Oracle database, which is installed as part of Oracle WebLogic Server, as the Web Clipping repository.

Example 64-1 shows MDS as the default repository in provider.xml.

Example 64-1 MDS as the Default Web Clipping Repository in provider.xml

  <repositoryInfo class="oracle.portal.wcs.provider.info.MdsInformation">
    <mdsConfigLocation>mds-config.xml</mdsConfigLocation> 
  </repositoryInfo>

For an MDS repository, the repositoryInfo tag is set to the MdsInformation class. The mdsConfigLocation entry specifies the path to the mds-config.xml file, which contains the metadata store configuration information, including the path to the actual metadata store. In Oracle JDeveloper, the mds-config.xml file is located at the following path:

JDEV_SYSTEM_DIRECTORY/DefaultDomain/servers/DefaultServer/tmp/_WL_user/portalTools_11.1.1.2.0/RANDOMLY_GENERATED_DIRECTORY/war/WEB-INF

Note:

On a Windows platform, pages in Framework applications are not rendered if there is a space in the path to the system directory in JDeveloper. Therefore, ensure that the JDEV_SYSTEM_DIRECTORY path does not contain spaces.

The mds-config.xml file specifies the location of the repository in a property tag:

<property name="metadata-path" value="portletdata/tools/webClipping"/>

The location specified for value is relative to JDEV_HOME/portal. Any relative path specified is interpreted to be relative to JDEV_HOME/portal. To use another location, for example, a location outside the Oracle JDeveloper home, then specify an absolute path, such as c:\mds.

Note:

For a multiple middle tier deployment, change the metadata path to a shared file system.

64.5.1.2 Using an Oracle Database as the Web Clipping Repository

Although MDS is the default repository in Oracle JDeveloper, you can alternatively select to use a database schema for your Web Clipping repository.

Note:

If you use a database as your Web Clipping repository, any customizations are retained even if the Web Clipping producer or the consuming application is redeployed.

You can use either of the following database schemas for Web Clipping:

  • The default PORTLET database schema created by RCU for Oracle WebLogic Server

  • A user-defined database schema for Oracle 9i or later

Note:

You cannot use a Microsoft SQL Server or IBM DB2 database as the Web Clipping repository.

This section includes the following subsections:

64.5.1.2.1 Using the Database Schema Created by RCU

For Web Clipping repository, you can use the Oracle database installed as part of Oracle WebLogic Server, through a JNDI data source named jdbc/portletPrefs. To access the database, the schema named PORTLET is used.

Note:

The PORTLET schema must be created in the Oracle database configured for WebCenter Portal. For more information, see the "Installing WebCenter Portal" chapter in the Oracle Fusion Middleware Installation Guide for Oracle WebCenter Portal.

64.5.1.2.2 Creating a Database Schema

You can use any user-defined schema for an Oracle 9i or later database as the Web Clipping repository. To create a database schema for Web Clipping definitions and clippings, run the Java command described in Example 64-2.

Example 64-2 Java Command for Creating a Schema for Web Clipping Portlet Definitions and Clippings

java -classpath WC_ORACLE_HOME/lib/xmlparserv2.jar:
WC_ORACLE_HOME/jdbc/lib/ojdbc14.jar:WC_ORACLE_HOME/portal/jlib/wce.jar
oracle.portal.wcs.Installer -installSchema -username dbuser -password
dbpassword -dburl jdbc:oracle:thin:@//host:port/dbid

Where:

  • WC_ORACLE_HOME is the path to your WebCenter Portal Oracle home directory

  • dbuser is the database user for the schema

    Consider using the same database user you use to create the WSRP and PDK-Java preference store database schema. If you do not use the same user, then you must create a new user and grant it connect and resource privileges.

  • dbpassword is the specified user's password

  • dburl is the URL for the database

    This is the database that contains the schema that you create for Web Clipping portlet definitions and clippings by using the following syntax:

    jdbc:oracle:thin:@//dbhost:dbport/service_name

    For example:

    jdbc:oracle:thin:@//shobeen:1521/sales_us

Note:

The classpath in Example 64-2 uses different separators for UNIX and Windows. On UNIX systems, the classpath uses a colon (:) separator. On Windows systems, the classpath uses a semicolon (;) separator.

64.5.1.3 Configuring Web Clipping Repository in provider.xml

To change the repository configuration for the Web Clipping producer deployed to Integrated WLS:

  1. Open the provider.xml file in a text editor.

  2. Specify the setting for your Web Clipping repository:

    • Use the PORTLET schema referred by the JNDI data source created by RCU. Specify the entries shown in Example 64-3.

      Example 64-3 Oracle Database as the Web Clipping Repository

        <repositoryInfo class="oracle.portal.wcs.provider.info.JdbcDbInformation">
     <connectionName>jdbc/portletPrefs</connectionName>
     <useRAA>false</useRAA>
     <useASO>false</useASO>
  </repositoryInfo>

      For information about tag parameters, see Section 64.5.1.4, "Attributes and Child Tags of the repositoryInfo Tag."

    • Use the database schema, created for an Oracle database 9i or later, where you can manually specify connection information.

      To specify Oracle 9i or later database as the Web Clipping repository, specify database connection parameters in the entry shown in Example 64-4.

      Example 64-4 Setting Oracle Database 9i or Later as Web Clipping Repository

          <repositoryInfo class="oracle.portal.wcs.provider.info.DatabaseInformation">
       <useRAA>false</useRAA>
       <databaseHost>dbhost.mycompany.com</databaseHost>
       <databasePort>1521</databasePort>
       <databaseSid>iasdb</databaseSid>
       <databaseUsername>scott</databaseUsername>
       <databasePassword>!tiger</databasePassword>
       <useASO>false</useASO>
    </repositoryInfo>

      For information about tag parameters, see Section 64.5.1.4, "Attributes and Child Tags of the repositoryInfo Tag."

      If you require a secure database connection, then enable the Advanced Security Option (ASO) by setting the useASO entry to true. For more information about configuring ASO, see Section 64.5.3, "Web Clipping Producer Security."

      Note:

      Only one entry of <repositoryInfo> can exist in provider.xml. Depending on the Web Clipping repository you choose, you must uncomment only that entry.

  3. Save the provider.xml file.

  4. Restart Integrated WLS.

64.5.1.4 Attributes and Child Tags of the repositoryInfo Tag

Table 64-1 lists and describes the attributes and child tags of the repositoryInfo tag.

Note:

The attributes and child tags of the repositoryInfo tag are also described in the comments in the Web Clipping provider.xml file.

In the comments in the provider.xml file, the example provided for Oracle9i Database or later using Oracle infrastructure database is specific to Oracle Portal and its infrastructure database and application programming interfaces. That example must not be used for Framework application implementations.

Table 64-1 Attributes and Child Tags of the repositoryInfo Tag

Attributes/Parameter MDS/Database Description

class

Both

The class attribute specifies the type of repository used to store Web Clipping definitions. The possible values for this attribute are:

  • oracle.portal.wcs.provider.info.MdsInformation

    This value signifies that MDS is used to store Web Clipping definitions and that MDS configuration is pushed to the mds-config.xml file.

  • oracle.portal.wcs.provider.info.DatabaseInformation

    This value signifies that an Oracle9i Database or later is used to store Web Clipping definitions and that the database connection details are included as children in the repositoryInfo tag.

  • oracle.portal.wcs.provider.info.JdbcDbInformation

    This value signifies that Oracle database installed as part of Oracle WebLogic Server is used to store Web Clipping definitions.

mdsConfigLocation

MDS

Use the mdsConfigLocation tag when the value for the class attribute indicates an MDS repository. It points to the MDS configuration file mds-config.xml, which specifies the actual MDS location. The mds-config.xml file is located at:

MW_HOME/wlserver_10.3/wc_domain/servers/WLS_Portlet/tmp/_WL_user/portalTools_11.1.1.2.0/yyggl7/war/WEB-INF

connectionName

Database

Specifies the JNDI name of the data source where the Web Clipping repository has been installed using the RCU. By default, the connection name is jdbc/portletPrefs, which points to the PORTLET schema in Oracle WebLogic Server.

In an interoperability scenario where an Oracle WebLogic Server 11g Middle Tier is paired with an Oracle Application Server 10g repository, the connection points to the PORTAL schema in the Oracle Application Server 10g repository.

useASO

Database

Set to true or false:

  • Specify true to use Oracle Advanced Security Option (ASO) to encrypt the communication channel between the Web Clipping producer and the database. This is provided for introducing added security if case-sensitive data is contained in the clipped content.

  • Specify false to omit this option.

useRAA

Database

Set to true or false:

  • Specify true if Repository Access APIs are used to access the database connection parameters. Specifying true is equivalent to making the Web Clipping producer use the default Oracle infrastructure database as the repository.

    Specifying true removes the need for other repositoryInfo child tags.

  • Specify false to omit this option.

databaseHost

Database

Specify the host name of the Oracle database. Use only version 9i or later. For example:

mycompany.dbhost.com

databasePort

Database

Specify the port number of the Oracle database listener. This is usually 1521.

databaseSid

Database

Specify the Oracle SID of the database that hosts the Web Clipping repository.

databaseUsername

Database

Enter the user name used to log in to the database.

databasePassword

Database

Enter a plain text password for the specified database user name. Prefix the password with an exclamation point (!) to allow the Web Clipping producer to encrypt the password when the producer starts.

For example:

!AX3tR

64.5.1.5 Migrating the Web Clipping Repository

By default, Web Clipping uses MDS, which is file-based, to store Web Clipping definitions and associated metadata. But you can configure Web Clipping to use a database. To migrate this repository for Framework applications, you can use the Predeployment tool in export and import mode to go from MDS to a database, or vice versa. This procedure must be done for each application as follows:

  1. Run the Predeployment tool in export mode on all Framework applications that use the Web Clipping producer.

  2. Update the producer to use a different repository. For information, see Section 64.5.1.3, "Configuring Web Clipping Repository in provider.xml."

  3. Run the Predeployment tool in import mode on all Framework applications that use the Web Clipping producer.

64.5.2 HTTP or HTTPS Proxy Configuration

Your HTTP or HTTPS proxy settings must be set to allow the Web Clipping Studio to connect to web sites outside of your firewall. You can specify the settings by manually editing the provider.xml file.

Framework application administrators can set proxy settings manually according to the HTTP or HTTPS configuration. Edit the appropriate entries in the provider.xml file.

Example 64-5 shows the relevant portion of provider.xml.

Example 64-5 Proxy Settings

- <!-- 
 proxy information: Fill the following up if you have a proxy
 server between the provider and external sites.
   <proxyInfo class="oracle.portal.provider.v2.ProxyInformation">
      <httpProxyHost>proxy.mycompany.com</httpProxyHost>
      <httpProxyPort>80</httpProxyPort>
      <dontProxyFor>*.mycompany.com</dontProxyFor>
      <proxyUseAuth>true</proxyUseAuth>
      <proxyType>Basic</proxyType>
      <proxyRealm>realm1</proxyRealm>
      <proxyUseGlobal>false</proxyUseGlobal>
      <proxyUser>scott</proxyUser>
      <proxyPassword>!tiger</proxyPassword>
   </proxyInfo>
   
  -->

It is optional to specify values for the following tags: <proxyUseAuth>, <proxyType>, <proxyRealm>, <proxyUseGlobal>, <proxyUser>, and <proxyPassword>.

Table 64-2, describes the proxy settings you specify in the provider.xml file.

Table 64-2 Provider.xml Tags

Parameter Description

httpProxyHost

Enter the host name of a proxy server if one is required to make a URL connection from the Web Clipping producer to its data sources.

httpProxyPort

Enter the port number for the HTTP Proxy Host.

dontProxyFor

Enter the name of any domain or hosts 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, *.us.company.com

Hosts can be fully qualified host names or can be IP addresses.

proxyUseAuth

Acceptable values: true | false

Enter true if your proxy server requires authentication. The authentication parameters are specified by the following tags: proxyType, proxyRealm, proxyUseGlobal, proxyUserName, and proxyPassword.

proxyType

Acceptable values: Basic | Digest

Choose the type of proxy server this provider.

For more information about basic or digest authentication, see http://www.faqs.org/rfcs/rfc2617.html.

proxyRealm

Enter the name of the realm of the proxy server that is accessed by the user according to the login information described later in the table. If you do not know the name of the realm, then contact the administrator of the proxy server.

proxyUseGlobal

Acceptable values: true | false

If true, then the <proxyUser> and <proxyPassword> values are used for all users. Users do not see the Proxy Authentication section on the Source tab and Personalize page. If false, then page designer must log in using the Proxy Authentication section on the Source tab when they define the portlet. The end user must log in using the Proxy Authentication section on the Personalize screen. If <proxyUsername> and <proxyPassword> are given, then they are only used for public users.

proxyUserName

Enter the user name to log in to the proxy server.

ProxyPassword

Enter the password for the specified user name. You must prefix ! before your plain password text. It is then encrypted in the provider.xml file for protection when the producer starts.

Note:

For environments that use a proxy server to reach external web sites, you can use the dontProxyFor entry to specify the proxy exception list. Web Clipping uses the proxy exception list to restrict users from clipping content from unauthorized external web sites. Users attempting to reach a web site in a listed domain, from the Web Clipping Studio, receive an HTTP timeout error.

64.5.3 Web Clipping Producer Security

The preceding sections described the administrative tasks that must be performed before you are able to use the Web Clipping producer. The following sections describe some security configuration options that you must implement to enable the Web Clipping producer to access Secure Sockets Layer (SSL)-enabled web sites and encrypt the channel between itself and the database:

64.5.3.1 Adding Certificates for Trusted Sites

When a user navigates to a secure site, the web site typically returns a certificate, identifying itself to the user when asking for secure information. If the user accepts the certificate, then the certificate is placed into the list of trusted certificates of the browser so that a secure channel can be opened between the browser and that server. Like a web browser, the Web Clipping producer acts as an HTTP client to external web sites. To keep track of trusted sites, the Web Clipping producer uses the cacerts file, which is the Java keystore to store trusted certificates.

By default, the cacerts file stores various certificates including the Equifax, VeriSign, and Cybertrust certificates. However, it does not include all possible server certificates that exist on the web. For this reason, when a user navigates to a secure server using HTTPS, the user can get an SSL handshake failed exception in the Web Clipping Studio. To solve this problem, you must add the certificate of that site to the cacerts file.

To add a certificate to the cacerts file:

  1. Download the certificate of the HTTPS web site and save the certificate in the PEM format.

    Tip:

    Mozilla Firefox 3.0 or later enable you to save a certificate file in the PEM format.

  2. Locate the path to the cacerts file:

    1. Log in to the Oracle WebLogic Server Administration Console by using the following URL format:

      http://host:port/console

    2. Open the Keystore tab for the WLS_Portlets managed server.

    3. Note down the location of the cacerts file given in the Java Standard Trust Keystore field.

      Figure 64-5 Locating the cacerts file

      Description of Figure 64-5 follows
      Description of "Figure 64-5 Locating the cacerts file"

  3. At the command prompt, navigate to the location of the cacerts file and run the following command to add the certificate:

    keytool -importcert -alias certi_alias -file certifi_name -keystore cacerts -storepass password

    Where, certi_alias refers to the alias used for the certificate, certifi_name refers to the certificate file name, and password refers to the password of the cacerts file. The default password is changeit.

    For example,

    keytool -importcert -alias stamf05 -file stamf05.crt -keystore cacerts -storepass changeit

    Tip:

    It is advisable to import trusted certificate into the cacerts file by using an alias. It makes it easier for you to delete or list the entries in the keystore.

64.5.3.2 Configuring Oracle Advanced Security for the Web Clipping Producer

The Web Clipping producer can use Oracle Advanced Security Option (ASO) to secure and encrypt the channel between itself and the database that hosts the Web Clipping repository. This feature is available only if you have selected any Oracle database as the Web Clipping repository. This feature is disabled by default as Oracle Metadata Services is the default Web Clipping repository in Oracle JDeveloper.

To enable ASO:

  1. Open provider.xml in a text editor.

  2. Under the repository settings section in the file (shown in Example 64-3), set the useASO entry to true.

  3. Save the provider.xml file.

In addition, you must set the following ASO configuration parameters in the sqlnet.ora file to ensure that the database connections created between the Web Clipping producer and the database hosting the Web Clipping repository are using ASO.

  • SQLNET.AUTHENTICATION_SERVICES -- This parameter is used to select a supported authentication method in making database connections with ASO. For more information about setting this parameter, see the Oracle Database Advanced Security Administrator's Guide.

  • SQLNET.CRYPTO_SEED -- This parameter denotes the cryptographic seed value (FIPS 140-1 setting), used in making database connections with ASO.

    For more information about setting parameters and about the values to use for various possible combinations of parameters, see the Oracle Database Advanced Security Administrator's Guide.

    Note:

    When setting these parameters after the initial configuration (where the database parameters are already set up), database connections are assumed to be open. Because enabling the ASO affects all connections made to the database, it is advisable to restart Integrated WLS containing the Web Clipping producer to reset all the current connections to use ASO. You must also do this when disabling ASO.

64.6 Current Limitations of Web Clipping

When you use Web Clipping, you should be aware of the following limitations.

  • If the site that you intend to clip uses a large amount of JavaScript to manipulate cookies or uses the document.write JavaScript method to modify the HTML document being written, then you may not be able to clip content from the site.

  • When you integrate with partner applications (by using mod_osso), you cannot clip directly through those partner applications in an authenticated manner. However, you can use partner applications through the external application framework.

  • You cannot use the Web Clipping portlet to clip Oracle Portal pages and ADF pages. As a workaround, reregister the same producer in the destination portal and edit the portal manually.

  • You cannot use the Web Clipping portlet to clip a web page that contains multiple frames, that is, a frameset.

  • Note the following about Web Clipping and the use of a CSS:

    • If a web page contains multiple portlets that use a CSS, then they should not conflict if the CSS uses distinct style names, such as OraRef, to specify a style within an HTML tag, rather than using an HTML tag name, such as <A>, as the name of the style.

    • If one portlet uses a CSS, and that CSS overwrites the behavior of HTML tags by using the name of the tag, such as <A>, as the name of the style, and a second portlet on the same page does not use a CSS, the second portlet is affected by the style instructions of the CSS of the first portlet.

    • If two portlets on the same page use a different CSS and each CSS overwrites the behavior of HTML tags by using the name of an HTML tag, such as <A>, as the name of the style, then the style that is displayed depends on the browser.

  • Web Clipping checks for globalization support settings in the following way:

    1. Web Clipping checks the Content-Type in the HTTP header for the charset attribute. If this is present, then it assumes that this is the character encoding of the HTML page.

    2. If the charset attribute is not present, then Web Clipping checks the HTML META tag on the page to determine the character encoding.

    3. If the HTML META tag is not found, then Web Clipping uses the charset in the previous browsed page. If this is the first page, then it defaults to the ISO-8859-1 character encoding.

    4. If the value of the charset for Content-Type or META tag is not supported (for example, if the charset was specified as NONE), then Web Clipping uses the default character set, ISO-8859-1, not the charset in the previously browsed page.

  • To use the Web Clipping portlet, you must use Netscape 7.0 or later, Microsoft Internet Explorer 5.5 or later for Windows 2000, or Microsoft Internet Explorer 6.0 or later for Windows XP. If you use browser versions older than these, then you may encounter JavaScript errors.

64.7 Troubleshooting Web Clipping

This section provides information to help you troubleshoot problems you may encounter while using Web Clipping.

Encountered "x" at line n, column n. Was expecting one of: "x", "y" ...

Parser error message written to the log file.

Problem

The web content displayed in the Web Clipping portlet contains invalid HTML or JavaScript.

Solution

This is a site-specific issue, not a Web Clipping error. Contact the site's administrator for assistance.