25 Managing the Pagelet Producer

Oracle WebCenter Portal's Pagelet Producer (previously called Oracle WebCenter Ensemble) provides a collection of useful tools that facilitate dynamic pagelet development and deployment. The Pagelet Producer proxy provides users with external access to internal resources including internal applications and secured content. Using the Pagelet Producer, you can expose WSRP and Oracle JPDK portlets and OpenSocial gadgets as pagelets for use in any web page or application.

This chapter describes how to register, edit and deploy pagelets using the Pagelet Producer Administrative Console.

This chapter includes the following sections:

For information about developing and deploying pagelets, see the section "Creating Pagelets with Oracle WebCenter Portal's Pagelet Producer" in the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter Portal.

Audience

The content of this chapter is intended for Fusion Middleware administrators. For more information, see Section 1.13, "Oracle WebCenter Portal Administration Tools."

25.1 About the Pagelet Producer

This section is an introduction to Pagelet Producer concepts and features and includes the following topics:

25.1.1 Key Concepts

The following key concepts are useful when working with the Pagelet Producer:

  • The Pagelet Producer Console is a browser-based administration tool used to create and manage the various objects in your Pagelet Producer deployment. From the Console you can register web applications as resources and create pagelets, manage proxy and transformation settings, and more.

    The Pagelet Producer Console is accessible through any web browser at the following URL: http://<host_name>:<port_number>/pagelets/admin.

    Any user with the 'Admin' role on the host application server can access the Pagelet Producer Console. To grant administrative access to the Pagelet Producer Console to users without administrative access to the application server, use the EnsembleAdmin role.

    The Pagelet Producer Console can also be launched in accessible mode at: http://<host_name>:<port_number>/pagelets/accessible.

  • Resources are core objects used to register applications within the Pagelet Producer, including stand-alone web applications, Portlet Producers and OpenSocial containers. Creating a resource allows the proxy to map internal applications to external URLs, manage authentication, and transform applications. Registering a web application as a Pagelet Producer resource allows you to do the following:

    • Proxy internal web applications to external addresses.

    • Manage authentication, both at the proxy level and at the resource level.

    • Transform proxied web applications, including URL rewriting.

  • Pagelets are sub-components of a web page accessed through the Pagelet Producer that can be injected into any proxied application. Any application on a Pagelet Producer resource that returns markup can be registered as a pagelet, which can then be displayed in Oracle WebCenter Portal, Spaces, or any web application.

    A pagelet is a reusable user interface component similar to a portlet. While portlets were designed specifically for portals, pagelets are designed to run on any web page. Any HTML fragment can be a pagelet. Pagelet developers can create pagelets that are parameterized and configurable, dynamically interact with other pagelets, and respond to user input using Asynchronous Javascript and XML (AJAX) patterns.

Pagelet Producer registration is dynamic. Additions and updates to existing producers are immediately available; in most cases, it is not necessary to restart the WebCenter Portal application or the managed server.

Note:

In the current release, only a single administrator can modify Pagelet Producer administrative settings at any given time. Concurrent edits will result in only one edit succeeding. However, data integrity will always be preserved.

25.1.2 Support for WSRP and Oracle JPDK Portlets

Using the Pagelet Producer, you can expose WSRP and Oracle JPDK portlets as pagelets for use in any web page or application.

After setting up the Pagelet Producer as described in Section 25.2, "Registering the Pagelet Producer," follow the steps below to import WSRP or Oracle JPDK portlets:

  1. Register the portlet producer with the Pagelet Producer as described in Section 25.9, "Registering WSRP and Oracle JPDK Portlet Producers in the Pagelet Producer."

  2. This automatically creates a resource and pagelets in the Pagelet Producer Console based on the portlet definitions for the producer. For details on the resource settings, see Section 25.4, "Creating Resources."

  3. To modify the imported resource or the associated pagelets, you must make a copy of the imported resource; for details, see Section 25.9.1, "Using WSRP and Oracle JPDK Portlets."

25.1.3 Support for OpenSocial Gadgets

Using the Pagelet Producer, you can expose OpenSocial gadgets as pagelets for use in any web page or application.

After setting up the Pagelet Producer as described in Section 25.2, "Registering the Pagelet Producer," follow the steps below to import OpenSocial gadgets:

  1. Define the OpenSocial container as described in Section 25.3.6, "OpenSocial Settings."

  2. Create an OpenSocial resource in the Pagelet Producer Console as described in Section 25.4, "Creating Resources" and Section 25.4.3, "Configuration Pages for OpenSocial Resources (OpenSocial Gadget Producers)."

  3. Create pagelets for OpenSocial gadgets as described in Section 25.5, "Creating Pagelets." The Pagelet Producer Console allows you to import gadget metadata from OpenSocial to populate the pagelet settings.

25.1.4 Support for Oracle WebCenter Interaction Portlets

The Pagelet Producer can be used as a portlet provider for Oracle WebCenter Interaction. There are several configuration pages that allow you to define CSP settings for use with Oracle WebCenter Interaction:

  1. Configure the Pagelet Producer settings for use with the Oracle WebCenter Interaction Credential Mapper, SOAP API service and image service, see the CSP Settings in Section 25.3, "Configuring Pagelet Producer Settings."

  2. Set up the Pagelet Producer's connection to the server hosting the portlet code by creating a CSP resource as described in Section 25.4, "Creating Resources."

  3. Create pagelets for the Oracle WebCenter Interaction portlets as described in Section 25.5, "Creating Pagelets."

25.2 Registering the Pagelet Producer

This section describes how to register and configure the Pagelet Producer using Fusion Middleware Control and WLST commands. This section includes the following subsections:

For information about developing and deploying pagelets, see the section "Creating Pagelets with Oracle WebCenter Portal's Pagelet Producer" in the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter Portal.

25.2.1 Registering the Pagelet Producer for WebCenter Portal Applications Using Fusion Middleware Control

To register the Pagelet Producer using Fusion Middleware Control:

  1. Log in to Fusion Middleware Control and navigate to the home page for your WebCenter Portal application. For more information, see:

  2. Do one of the following:

    • For the Spaces application - From the WebCenter Portal menu, select Register Producer.

    • For Framework applications - From the Application Deployment menu, select WebCenter Portal, then Register Producer.

  3. Enter connection details for the Pagelet Producer (Table 25-1).

    Table 25-1 Pagelet Producer Connection Parameters

    Field Description

    Connection Name

    A unique name to identify this Pagelet Producer instance within the WebCenter Portal application. The name must be unique across all WebCenter Portal connection types. The name specified here appears in Composer under the Mash-ups > Pagelet Producers folder (by default).

    Producer Type

    Select Pagelet Producer.

    Server URL

    The URL to the Pagelet Producer. The URL must include a fully-qualified domain name. Use the following syntax:

    <protocol>://<host_name>:<port_number>/pagelets/

    For example:

    http://myhost.com:7778/pagelets/

    If pagelets contain secure data, the registered URL must use the https protocol. For example:

    https://myhost.com:7779/pagelets/

    The context root can be changed from /pagelets/ if necessary; for details, see Section 25.11.1, "Redeploying the Pagelet Producer to a Different Context."

    Note: In Spaces, if the Pagelet Producer URL is protected by OAM, the URL to the pagelet catalog must be excluded (mapped directly without access control), or the catalog will appear to be empty when using REST. The pagelet catalog URL is http://<host_name>:<port_number>/ pagelets/api/v2/ensemble/pagelets

  4. Click OK. The new producer appears in the connection table.

25.2.2 Registering the Pagelet Producer for WebCenter Portal Applications Using WLST

Use the registerPageletProducer command to register a Pagelet Producer for your WebCenter Portal application. For command syntax and examples, see the section "registerPageletProducer" in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

You can also use WLST to list or edit the current connection details.

For information on how to run WLST commands, see Section 1.13.3.1, "Running Oracle WebLogic Scripting Tool (WLST) Commands."

25.2.3 Configuring the Pagelet Producer Service for WebCenter Portal

This section describes how to set up the Pagelet Producer for use as a service by Oracle WebCenter Portal using the Oracle Configuration Wizard.

To set up the Pagelet Producer as a WebCenter Portal service:

  1. Launch the Configuration Wizard (Oracle Fusion Middleware > Oracle WebLogic Server > Tools > Configuration Wizard).

  2. Select Create a new WebLogic Domain. Click Next.

  3. Select Base this domain on an existing template and select the Pagelet Producer domain template. Confirm that the template location is correct and click Next.

  4. Complete the domain configuration wizard. For details, see the online help.

All post deployment connection configuration is stored in the Oracle Metadata Services (MDS) repository. For more information, see Section 1.3.5, "WebCenter Portal Configuration Considerations." For detailed information about MDS, see the chapter "Managing the Oracle Metadata Repository" in the Oracle Fusion Middleware Administrator's Guide.

The Pagelet Producer stores all configuration data on a separate partition in the MDS schema of RCU. Typically, this schema is installed as part of the Oracle WebCenter Portal installation. This configuration data does not conflict with data that belongs to other services. When the Pagelet Producer domain template is deployed, the wizard prompts for connectivity information to the database in which the schema has been created. The names that the Pagelet Producer expects are:

  • Datasource Name: mds-PageletProducerDS

  • JNDI name: jdbc/mds/PageletProducerDS

  • MDS partition name: pageletproducer

To use OpenSocial gadgets in conjunction with WebCenter Portal profile and activities features, you must manually configure the WebCenterDS data source to target the WC_Portlet server.

  1. In the Oracle WebLogic Server Console, go to Services > Data Source.

  2. Click on the WebCenterDS data source.

  3. Go to the Targets tab.

  4. Select the WC_Portlet server and click Save.

25.2.4 Registering Pagelet Producer Using WebCenter Portal: Spaces

This section explains how to register the Pagelet Producer in WebCenter Portal: Spaces.

  1. Log in to Spaces and click Administration.

  2. Navigate to the Configuration tab and click Services.

  3. On the Services and Providers page, click Portlet Producers.

  4. Click Register and select Pagelet Producer.

  5. Enter connection details for the Pagelet Producer (Table 25-2).

    Table 25-2 Pagelet Producer Connection Parameters

    Field Description

    Producer Name

    A unique name to identify this Pagelet Producer instance within Spaces.

    Server URL

    The URL to the Pagelet Producer. The URL must include a fully-qualified domain name. Use the following syntax:

    <protocol>://<host_name>:<port_number>/pagelets/ where host and port correspond to the WC_Portlet managed server where the Pagelet Producer is configured.

    For example:

    http://myhost.com:7778/pagelets/

    If pagelets contain secure data, the registered URL must use the https protocol. For example:

    https://myhost.com:7779/pagelets/

    The context root can be changed from /pagelets/ if necessary; for details, see Section 25.11.1, "Redeploying the Pagelet Producer to a Different Context."

    Note: In Spaces, if the Pagelet Producer URL is protected by OAM, the URL to the pagelet catalog must be excluded (mapped directly without access control), or the catalog will appear to be empty when using REST. The pagelet catalog URL is: http://<host_name>:<port_number>/ pagelets/api/v2/ensemble/pagelets

25.3 Configuring Pagelet Producer Settings

The Settings section in the Pagelet Producer Console provides access to important configuration settings that affect all Pagelet Producer resources. For an introduction to the Pagelet Producer Console, see Section 25.1, "About the Pagelet Producer.".

The following pages are included in the Settings section:

25.3.1 Logging Settings

The Logging page allows you to set logging levels for Pagelet Producer components.

Figure 25-1 Pagelet Producer Console: Settings - Logging

Description of Figure 25-1 follows
Description of "Figure 25-1 Pagelet Producer Console: Settings - Logging"

To enable logging for any component, select one of the following logging levels:

  • Severe

  • Warning

  • Info

  • Config

  • Fine

  • Finer

  • Finest

Logging messages can be viewed in the managed server log files. In Oracle WebLogic Server, this would be domain_home/servers/managed server name/managed server name.log and managed server name-diagnostic.log.

25.3.2 Proxy Settings

The Proxy page allows you to define a semicolon-separated list of URLs that will not be proxied (wildcards are allowed), and set the HTTP proxy configuration if necessary (URL, user name and password).

You must restart the Pagelet Producer after changing the proxy settings.

Note:

If an HTTP proxy is required for external connections in the deployment environment, initial server startup will report connection errors. These errors are not an indication of problems with the environment; they indicate that some external OpenSocial libraries cannot be loaded remotely. The errors can be resolved by configuring the proxy settings as described above and restarting the server.

Note for Oracle WebLogic Server deployments:

The HTTP Proxy Server URL entered on the Proxy page is applied to all applications running on the server that hosts the Pagelet Producer (on Oracle WebLogic Server, this setting is applied to all applications running on the WC_Portlet managed server). Oracle WebLogic Server users should pay particular attention to this setting and make sure that the WLS Administrative Server host and all clustered managed servers are included in the "Do not proxy hosts" list.

Figure 25-2 Pagelet Producer Console: Settings - Proxy

Description of Figure 25-2 follows
Description of "Figure 25-2 Pagelet Producer Console: Settings - Proxy "

25.3.3 Transform Settings

The Transform page allows you to enter the path to the credential vault provider and configure secure and insecure ports for the Pagelet Producer. This page also allows you to choose whether or not to intercept and transform Ajax requests, and whether or not to log pre- and post- transformation content (this option can be useful for debugging, but should not be enabled in a production environment).

Note:

The Nonsecure Port defaults to 8889. If the Pagelet Producer is deployed on a different port, change this entry and restart the server.

Figure 25-3 Pagelet Producer Console: Settings - Transform

Description of Figure 25-3 follows
Description of "Figure 25-3 Pagelet Producer Console: Settings - Transform"

25.3.4 CSP Settings

CSP is a platform-independent protocol based on the open standard of HTTP 1.1. CSP defines the syntax of communication between the Pagelet Producer and external resources. It also defines custom headers as well as outlines how services use HTTP to communicate and modify settings.

This page allows you to configure the Oracle WebCenter Interaction Credential Mapper, SOAP API service, and image service.

Note:

This page may be ignored if Oracle WebCenter Interaction is not present in your deployment. These settings are used for backwards compatibility with CSP portlets written for Oracle WebCenter Interaction.

25.3.5 Kerberos Settings

This page is used to define the paths to the Kerberos configuration files (java.security.krb5.conf and java.security.auth.login.conf). These two configuration files are needed to configure the Kerberos realm and KDC to instruct HTTPClient where to retrieve the Kerberos Service ticket.

25.3.6 OpenSocial Settings

This page allows you to configure the Pagelet Producer for use with OpenSocial gadgets.

Figure 25-4 Pagelet Producer Console: Settings - OpenSocial

Description of Figure 25-4 follows
Description of "Figure 25-4 Pagelet Producer Console: Settings - OpenSocial"

This page includes the following settings:

  • The Context field defines the context to which the Pagelet Producer is deployed. This value should be left at the default setting ("pagelets") unless a change is required by the OpenSocial container. For details on changing the context, see Section 25.11.1, "Redeploying the Pagelet Producer to a Different Context."

  • The Host field should contain the fully-qualified domain name of Pagelet Producer host. This value should be retrieved automatically from the environment; if it is not, restart the server to pick up the correct configuration settings. As with the Context setting, this value should be left at the default unless a change is required by the OpenSocial container.

  • The Cache option enables Pagelet Producer internal caching for OpenSocial gadgets.

  • The Debug option enables debugging for OpenSocial gadgets (disables JavaScript obfuscation).

  • The SSL option enables SSL for OpenSocial gadgets.

Note:

You must also configure the secure (HTTPS) and nonsecure (HTTP) ports before importing OpenSocial gadgets. For details on these settings, see Section 25.3.3, "Transform Settings."

25.4 Creating Resources

As noted in Section 25.1, "About the Pagelet Producer," resources are applications registered with the Pagelet Producer. Registering an application as a resource allows the proxy to map internal applications to external URLs, manage authentication, and transform application functionality.

To create a new resource, use the steps below:

  1. Select the Resources option from the dropdown list in the Pagelet Producer Console navigator.

  2. Click on any existing resource and click the Create icon in the navigator toolbar. (This button is only enabled when you have selected an object type that can be created.)

    Figure 25-5 Pagelet Producer Console - Create Resource

    Description of Figure 25-5 follows
    Description of "Figure 25-5 Pagelet Producer Console - Create Resource"

  3. In the Select Producer Type dialog box, select the type of producer that the resource will be configured to proxy from the dropdown list:

    Figure 25-6 Select Producer Type Dialog

    Description of Figure 25-6 follows
    Description of "Figure 25-6 Select Producer Type Dialog"

  4. Click OK. An entry called "<new>" will be added to the list of resources. This new resource will include the necessary configuration pages for the producer type chosen.

  5. Configure the resource in the Pagelet Producer Console. The required configuration pages differ based on the type of producer. To save your changes at any time, click the Save icon in the navigator toolbar.

Once the resource is defined, create pagelets and other objects within the resource.

25.4.1 Configuration Pages: Web and CSP Resources

The following configuration pages are used for Web and CSP resources:

This section uses the welcome_resource created when the Pagelet Producer is installed as an example.

25.4.1.1 General

On the General page, enter basic information about the resource.

Figure 25-7 Pagelet Producer Console: Resource - General Page

Description of Figure 25-7 follows
Description of "Figure 25-7 Pagelet Producer Console: Resource - General Page"

  • Enter a Name for the resource.

  • Enter a Description for the resource (optional).

  • In the Source URL field, type the URL to the location of the web application resource to be proxied. For example, http://internalServer/foo/.

    Note:

    If you are configuring an ADF Web Application as a resource, the Source URL cannot be any more specific than http://hostname:portnumber/context-root/.

  • By default, the Pagelet Producer attempts to connect to the resource for 30 seconds before returning an error message. To change this value, enter a new Source Timeout period in seconds.

  • In the Destination URL field, type the relative path to be used to access the resource. This path will be used to create an URL to the resource on the server that hosts the Pagelet Producer.

  • The Pagelet Producer enables URL Rewriting by default. When URL rewriting is enabled, the Pagelet Producer rewrites URLs in the proxied application that begin with the source URL prefix so that they point to the destination URL prefix. If any URLs point to other proxied CSP or web applications (also registered with the Pagelet Producer), those URLs will also be rewritten to use the proxy.

    There are two cases in which you should disable URL rewriting:

    • The internal URL prefix and external URL prefix are identical. In this case, the user's DNS must resolve the URL to the Pagelet Producer proxy server, and the Pagelet Producer proxy server's DNS must resolve the URL to the internal resource. Because DNS only resolves IP and not port, both servers must listen to the same port. This method is strongly recommended.

    • All links in the application are relative URLs. In this case, the internal URL prefix path and the external URL prefix path must be identical. For example, if the internal URL prefix is http://internal_server/bar/ the external URL prefix path must be /bar/ or http://proxy_server/bar/.

    To disable transformation, deselect URL Rewriting.

  • To enable Dynamic HTML, select DHTML Rewriting. This option supports URLs that are not in the original HTML returned from the server, but are added by DHTML. In most cases, this option should be enabled.

25.4.1.2 CSP

The preference headers specified on the CSP page are passed between the Pagelet Producer and remote CSP content producers. Basic preference types are supported natively and other preference types are mapped to one of the basic types.

Note:

When accessing content that is built using web standards (javascript and HTML), these settings can be ignored or leveraged partially by sending the CSP-Set-Preference and CSP-Get-Preference headers as documented by the CSP protocol.

Figure 25-8 Pagelet Producer Console: Resource - CSP Page

Description of Figure 25-8 follows
Description of "Figure 25-8 Pagelet Producer Console: Resource - CSP Page"

User and session scope preferences can be shared by more than one pagelet. CSP metadata can be used to specify which session preferences can be set or obtained from the application and which user info preferences will be sent to the application. For example, if you store personally identifiable information such as an employee ID as a user preference, you can control which pagelets have access to this information.

By default, the CSP login token is not passed to the proxied resource. To enable this feature, select Send CSP Login Token. You must also enter the name and type of each of the settings that should be retrieved from the Pagelet Producer.

Note:

Pagelets associated with a resource inherit this metadata.

25.4.1.3 Policy

The Policy page allows you to limit access to a resource to specific roles within Oracle WebCenter Portal.

Figure 25-9 Pagelet Producer Console: Resource - Policy Page

Description of Figure 25-9 follows
Description of "Figure 25-9 Pagelet Producer Console: Resource - Policy Page"

The J2EE container hosting the Pagelet Producer (such as Oracle WebLogic Server) is responsible for establishing the role memberships associated with the current user. A resource can specify multiple roles on the Policy page, and users will be allowed access if they are a member of any of the specified roles; otherwise they will be directed to a suitable J2EE container delegated authentication page to establish the required credentials. If no roles are entered in the list, anonymous access is allowed, and the resource is termed as an "anonymous resource".

Note:

The role name(s) entered on this page must match those created in the J2EE container (such as Oracle WebLogic Server).

25.4.1.4 Autologin

The autologin feature allows the Pagelet Producer to supply credentials to applications automatically. The Autologin page allows you to configure authentication information for a resource for use by all users who access the resource.

Figure 25-10 Pagelet Producer Console: Resource - Autologin Page

Description of Figure 25-10 follows
Description of "Figure 25-10 Pagelet Producer Console: Resource - Autologin Page"

The sections that follow describe how to configure credential mapping for authentication:

25.4.1.4.1 Form Login

This section describes how to configure autologin for a resource that prompts for authentication with an HTML form.

  1. On the Autologin page for the resource, expand the Form Login section.

  2. The login page can be identified by an URL or a regular expression. In the Login Form Identification section, select one of the following options:

    • If the login form is located at a static URL, select URL and type the URL into the box. You can choose to Automatically Detect Form Fields on the page or enter them manually as described in step 5 below.

    • If the login form is dynamic, select RegEx and type the regular expression pattern into the box.

  3. Set the login form action. In the Form Submit Location section, select one of the following options:

    • If the login form action is a static URL, select URL and type the URL into the box. Select the action for the form submission: POST or GET.

    • If the login form is dynamic, select RegEx and type the regular expression pattern into the box.

  4. To map fields from the form to authentication field sources, either click Automatically Detect Form Fields in the Login Form Identification section or enter them manually using the process below:

    1. Click Create to add a new row to the Form Fields list.

    2. Type the name of the HTML form input in the Field Name box.

    3. For details on how to configure the Source and Value properties, see Section 25.4.1.4.4, "Authentication Sources."

      Note:

      Sensitive fields should be stored securely using the credential vault (User Vault or Shared Vault).

    4. To delete field mappings, click Delete.

  5. The logout page and login error pages can also be identified by an URL or a regular expression. In the Logout Page Identification and Login Error Page Identification sections, select one of the following options:

    • If the page is located at a static URL, select URL and type the URL into the field provided.

    • If the page is dynamic, select RegEx and type the regular expression pattern into the field provided.

25.4.1.4.2 Basic Login and NTLM Login

This section describes how to configure autologin for a resource that prompts for authentication with basic authentication or NTLM.

  1. On the Autologin page for the resource, expand the Basic Login or NTLM Login section.

    Note:

    "Basic authentication transmits passwords as plain text, and therefore, it must not be used in production systems. Further, it is strongly recommended that the underlying transport is HTTPS.

  2. In the Username and Password sections, select the appropriate authentication source and enter a value as necessary. For details on how to configure these properties, see Section 25.4.1.4.4, "Authentication Sources".

25.4.1.4.3 Kerberos Login

This section describes how to configure autologin for a resource that prompts for authentication using Kerberos. For information on defining basic Kerberos settings, see Section 25.3, "Configuring Pagelet Producer Settings."

  1. On the Autologin page for the resource, expand the Kerberos Login section.

  2. In the Username and Password sections, select the appropriate authentication source and enter a value as necessary. For details on how to configure these properties, see the next section, Section 25.4.1.4.4, "Authentication Sources".

  3. In the SPN field, enter the Service Principal Name (SPN) for the Kerberos account, in the format http://hostname_with_kerberos. (Before the Kerberos authentication service can use an SPN to authenticate a service, the SPN must be registered on the account object that the service instance uses to log on.)

25.4.1.4.4 Authentication Sources

Authentication sources define the source for login fields. The following table describes each of the authentication field source values:

Table 25-3 Pagelet Producer Authentication Sources

Field Description

Static

Uses the provided authentication information for all users accessing the resource. Type the static value in the field provided.

Profile

Passes the name associated with a WebCenter Portal user profile to the resource. Type the name of the parameter that stores the username in the field provided.

Note: Do not use the Profile option for passwords. Oracle security guidelines state that passwords must be stored in a credential vault. Instead use the User Vault or Shared Vault option.

User Vault or
Shared Vault

Prompts the user for credentials the first time the resource is accessed. The supplied credentials are encrypted and stored in the credential vault, and each subsequent access to the resource is authenticated with the stored credentials. When using vault storage, the key name chosen should be a generic placeholder and should not reflect sensitive information like the actual password.In the second field, enter the name of the credential vault to use, or leave the entry as "default" to use the server vault.

User Vault stores one value per key per user, while Shared Vault stores one value per key for all users.

Note: If you select User Vault, the user will be presented with an error page that includes a link: "Click here to access pagelet directly." This link opens the authentication dialog. This is a known issue and occurs only the first time the resource is accessed by a user.

25.4.1.5 Headers

The Headers page allows you to choose Request and Response headers that should be dropped from the HTTP that is provided by the Pagelet Producer.

Figure 25-11 Pagelet Producer Console: Resource - Headers Page

Description of Figure 25-11 follows
Description of "Figure 25-11 Pagelet Producer Console: Resource - Headers Page"

Some header elements should be blocked from being passed to back-end applications. For example, when using delegated (third-party SSO) authentication, the SSO system might insert some headers that need not be passed to the back-end applications. When passed, these headers might interfere with the back-end application functionality.

If any headers are specified on this page, only the specified headers will be dropped. If no headers are explicitly specified, the following headers are dropped by default:

Request Headers Response Headers

- Cache-Control

- Connection

- Cookie

- Host

- Max-Forwards

- Pragma

- Proxy-Connection

- Proxy-Authorization

- TE

- Trailer

- Transfer-Encoding

- Upgrade

- Max-Forwards

- Proxy-Authenticate

- Proxy-Connection

- Set-Cookie

- Trailer

- Transfer-Encoding

- Upgrade

To add a header to the list, click Create and enter the header name in the field provided. The Content-Length header is always implicitly dropped, because manipulating content during the proxying operation renders the content length invalid in almost all cases.

Once the resource is defined, you can create pagelets and other objects within the resource.

25.4.2 Configuration Pages for WSRP/JPDK Resources (WSRP and Oracle JPDK Portlet Producers)

The following configuration pages are used for WSRP/JPDK resources, which are based on WSRP or Oracle JPDK portlet producers.

Note:

Before you can create a resource based on a WSRP or Oracle JPDK portlet producer, you must register the producer as described in Section 25.9, "Registering WSRP and Oracle JPDK Portlet Producers in the Pagelet Producer."

25.4.2.1 General

On the General page, enter basic information about the resource.

25.4.2.2 Policy

The Policy page allows you to limit access to a resource to specific roles within Oracle WebCenter Portal.

The J2EE container hosting the Pagelet Producer (such as Oracle WebLogic Server) is responsible for establishing the role memberships associated with the current user. A resource can specify multiple roles on the Policy page, and users will be allowed access if they are a member of any of the specified roles; otherwise they will be directed to a suitable J2EE container delegated authentication page to establish the required credentials. If no roles are entered in the list, anonymous access is allowed, and the resource is termed as an "anonymous resource".

Note:

The role name(s) entered on this page must match those created in the J2EE container (such as Oracle WebLogic Server).

Once the resource is defined, you can create pagelets and web injectors within the resource.

25.4.3 Configuration Pages for OpenSocial Resources (OpenSocial Gadget Producers)

The following configuration pages are used for OpenSocial resources, which are based on OpenSocial gadget producers.

Note:

Configure the Pagelet Producer for use with OpenSocial before creating an OpenSocial resource. For details, see Section 25.3.6, "OpenSocial Settings."

25.4.3.1 General

On the General page, enter basic information about the resource.

  • Enter a Name for the resource.

  • Enter a Description for the resource (optional).

  • The Source URL field should be pre-filled with the relative URL to the internal OpenSocial Container (/os/). Registering external OpenSocial Containers is not supported.

  • In the Destination URL field, type the relative path to be used to access the resource. This path will be used to create the URL to the OpenSocial container on the server that hosts the Pagelet Producer.

25.4.3.2 Policy

The Policy page allows you to limit access to a resource to specific roles within Oracle WebCenter Portal.

The J2EE container hosting the Pagelet Producer (such as Oracle WebLogic Server) is responsible for establishing the role memberships associated with the current user. A resource can specify multiple roles on the Policy page, and users will be allowed access if they are a member of any of the specified roles; otherwise they will be directed to a suitable J2EE container delegated authentication page to establish the required credentials. If no roles are entered in the list, anonymous access is allowed, and the resource is termed as an "anonymous resource".

Note:

The role name(s) entered on this page must match those created in the J2EE container (such as Oracle WebLogic Server).

Once the resource is defined, you can create pagelets and files within the resource.

25.5 Creating Pagelets

The pagelets collection lists the pagelets associated with the resource. To create a new pagelet, select the Pagelets section under the resource you want to use in the Pagelet Producer Console and click the Create icon in the toolbar. A pagelet called "<new>" will be added to the list. To modify an existing pagelet, click the pagelet name. Each pagelet has the following configuration pages:

25.5.1 General

Enter a Name for the pagelet and the Library name with which to associate the pagelet. (A pagelet library is a user-defined way to group related pagelets.) Enter a Description for the pagelet (optional).

The Refresh Inline option should be used only if the pagelet is to be injected into the page body without using an IFrame. Since IFrame injection is the default and recommended method for implementing partial page refresh for pagelet click-throughs, this option should only be enabled under very rare circumstances.

  • For web and CSP pagelets, type the relative path to the pagelet in the URL Suffix field (do not include the Source URL prefix you entered for the resource). If you leave the URL Suffix blank, then the entire resource will be considered the pagelet.

  • For pagelets based on WSRP or Oracle JPDK portlets, select the portlet on which to base the pagelet from the Portlet dropdown list. This list is populated with the portlets on the WSRP or Oracle JPDK portlet producer associated with the parent resource. Any public parameters associated with the portlet will automatically be imported as pagelet parameters. For more information on working with WSRP and Oracle JPDK portlets, see Section 25.9, "Registering WSRP and Oracle JPDK Portlet Producers in the Pagelet Producer" and Section 25.4.2, "Configuration Pages for WSRP/JPDK Resources (WSRP and Oracle JPDK Portlet Producers)."

  • For pagelets based on OpenSocial gadgets, enter the location of the gadget XML schema in the Gadget URL field. Click the Import Gadget Metadata button to import the following information from the XML schema:

    • Gadget name: This value will be imported into the Description field on the General page.

    • Gadget user preferences: The pagelet parameters on the Parameters page will be populated with the gadget's user preferences.

    • Preference editor: If there are any editable user preferences, the Personalize Editor field on the Preferences page will be populated and a preference page will be created using the preferences on the Parameters page.

25.5.2 Preferences

On the Preferences page, enter the relative URLs to any preference pages required by the pagelet: Global, Customize, or Personalize. Do not include the Source URL prefix you entered for the resource. (As noted above, for OpenSocial gadgets with user preferences, a default entry will be created; this entry should not be modified.)

The Preferences page is not used by WSRP or Oracle JPDK-based pagelets.

Figure 25-12 Pagelet Producer Console: Pagelets - Preferences Page

Description of Figure 25-12 follows
Description of "Figure 25-12 Pagelet Producer Console: Pagelets - Preferences Page"

25.5.3 Parameters

Data can be passed to pagelets using pagelet parameters or the pagelet payload. Parameters pass name-value pairs to the pagelet application, while the payload is any text, including XML. You can write an XML Schema to describe the XML that a particular pagelet expects and document this by entering a URI to and XSD file or a namespace:name qualifier on this page. This value is for convenience only, it is not used or enforced at runtime.

On the Parameters page, enter the Payload Schema or the Parameters that should be passed to the pagelet.

To add a parameter, click Create.

  • Enter the Name of the parameter.

  • Select the Transport type: Request Parameter, Administrative Preference, Community Preference, or Pagelet Preference.

    Note:

    The Request Parameter transport type should be use in most cases. Request Parameters are sent as query string arguments on the URL to the pagelet's host server. The preference transport types should only be used for CSP pagelets.

  • If the parameter is required by the pagelet, select the Required check box.

  • Select the appropriate data Type: string or numeric.

Figure 25-13 Pagelet Producer Console: Pagelets - Parameters Page

Description of Figure 25-13 follows
Description of "Figure 25-13 Pagelet Producer Console: Pagelets - Parameters Page"

25.5.4 Clipper

Clipping allows you to form a pagelet by clipping a portion of a larger web page in a proxied application. For example, in a news web page there is a box listing the latest headlines. By identifying the containing HTML for that box, you can clip only the headlines and serve that subset of the news web page as a pagelet.

To create a clipper, select the Clipper section under the pagelet and click the Create icon in the toolbar. A new clipper will be created with two configuration pages:

  • On the General page, enter a name for the clipper.

  • On the Content page, define the clipper content.

    In addition to clipping a portion of the body of the web page, the pagelet's <head> element can be included by choosing Include head. This allows CSS, JavaScript, or other declarations that occur in the <head> element to be included with the clipped body portion.

    • To use a graphical tool to select page content, click Launch Clipper.

    • To specify HTML tag attributes that describe the section to be clipped, expand the Advanced Clipper section and enter the tag name and associated attribute(s).

    Figure 25-14 Pagelet Producer Console: Clipper - Content Page

    Description of Figure 25-14 follows
    Description of "Figure 25-14 Pagelet Producer Console: Clipper - Content Page "

Keep the following in mind when using the clipper:

  • If the back-end resource is accessed over HTTPS, make sure the Pagelet Producer Console is also accessed over a secure port.

  • If the clip source is protected by a login form or other form of authentication, make sure to configure Autologin for the parent resource as described in Section 25.4.1.4, "Autologin". If you are using the vault to store credential values, make sure to capture the credentials prior to using the clipper.

  • If you are having problems with the clipper, make sure the configured pagelet URL can be loaded by the browser without redirects. If necessary, change the pagelet suffix to reflect the final URL loaded by the browser after following all the redirects.

  • Images and code overwritten using hosted files cannot be clipped. (For details on hosted files, see Section 25.8, "Creating Hosted Files.")

25.5.5 Documentation

The Documentation page displays sample code to access the pagelet and preference editor using either the JavaScript or REST API.

Figure 25-15 Pagelet Producer Console: Pagelets - Documentation Page

Description of Figure 25-15 follows
Description of "Figure 25-15 Pagelet Producer Console: Pagelets - Documentation Page "

25.6 Creating Web Injectors

A web injector inserts content into a specified location in the proxied resource page. The content may be any text, including HTML, CSS, JavaScript, and pagelet declarations. An empty injector may also be used to remove unwanted content from a page. Injectors cannot be created for OpenSocial resources.

To create a web injector, select the Injectors section under the resource you want to use and click the Create icon in the toolbar. A new injector called "<new>" will be added to the list. Injectors have the following configuration pages:

25.6.1 General

Enter a Name for the web injector.

The injector can be applied to a subset of the resource by typing a URL pattern into the URL Filter box. The injector will be applied only to those URLs within the resource that begin with the text in the URL Filter box. If the box is empty or contains only a '/', the injector will be applied to the entire resource.

To restrict the injector to specific kinds of content, type a comma separated list of MIME types in the MIME Filter box. For example, text/html restricts the injector to HTML content, while text/css only restricts the injector to CSS content.

Define where in the resource's output the injection will be made:

  • Top puts the content first in the page. Do not use this option to inject pagelet declarations.

  • Bottom puts the content last in the page.

  • The Before/After/Replace options put the content into the page relative to the unique string specified in the field provided. You can select to ignore the case of the string by selecting Ignore case.

    The Enclose tag option identifies the unique string and replaces both the text and the enclosing tag with the content specified on the next page.

Figure 25-16 Pagelet Producer Console: Injectors - General Page

Description of Figure 25-16 follows
Description of "Figure 25-16 Pagelet Producer Console: Injectors - General Page"

25.6.2 Content

Content to be injected may be any text, including HTML, CSS, JavaScript, and pagelet declarations. Content can be entered using the text editor or the HTML editor.

Figure 25-17 Pagelet Producer Console: Injectors - Content Page

Description of Figure 25-17 follows
Description of "Figure 25-17 Pagelet Producer Console: Injectors - Content Page "

25.7 Creating Custom Parsers

Custom parsers allow you to supplement or change built-in logic for parsing content and finding URLs. When the built-in parsers fail to identify URLs or identify sections that must not be rewritten as URLs, custom parsers can be used to change the default behavior. Parsers cannot be created for WSRP or Oracle JPDK portlet producers or OpenSocial gadget producers.

To create a custom parser, select the Parsers section under the resource you want to use and click the Create icon in the toolbar.

  • Enter a Name for the parser.

  • The parser can be applied to a subset of the resource by typing a URL pattern into the URL Filter box. The parser will be applied only to those URLs within the resource that begin with the text in the URL Filter box. If the box is empty or contains only a '/', the parser will be applied to the entire resource.

  • To add a new parsing rule, click Create to add a new row to the Fragment Locations section.

  • In the Regular Expressions column, enter the regular expression for identifying the URL fragment that should be transformed. The first grouping expression (in parentheses) identifies the fragment, and the rest of the expression provides the context for finding it.

  • Select the Fragment Type to define how the selected location should be parsed:

    • Static URLs are transformed on the server.

    • Dynamic URLs are transformed using JavaScript on the client.

    • HTML Fragment and Javascript Fragment types are used for content that is embedded in another content type, such as XML.

    • No Rewriting specifies a location that should not be searched for URLs. This option is used to prevent rewriting of markup mistakenly identified as URLs.

  • Click the Save icon in the navigator toolbar.

Figure 25-18 Pagelet Producer Console: Parsers - General Page

Description of Figure 25-18 follows
Description of "Figure 25-18 Pagelet Producer Console: Parsers - General Page"

25.8 Creating Hosted Files

The Pagelet Producer can host all types of content (HTML, JavaScript, CSS, etc.) and present the file at a virtual URL location. Hosted files can be used for a range of purposes:

  • Overwrite content and functionality in a proxied application, by uploading files and configuring them to use the same URL as the original file.

  • Use hosted files in injectors to insert images or content into a proxied application.

  • Host pagelet files on the Pagelet Producer server.

To upload a file, select the Files section under the resource you want to use and click the Create icon in the toolbar.

  • On the General page, enter the relative path to the file in the Name field. Do not use a leading forward-slash ("/"). The directory structure of the Files collection in the navigator is updated to match the path to the file.

    Enter the MIME type of the file.

    Figure 25-19 Pagelet Producer Console: Files - General Page

    Description of Figure 25-19 follows
    Description of "Figure 25-19 Pagelet Producer Console: Files - General Page"

  • On the Content page, enter the path to the file or click the Browse button to navigate to the file.

    Click the Upload button to upload the file to the Pagelet Producer server. If you entered text or html as the MIME type, you can also use the editor on the Content page to enter or edit file content. (The editor is only available for text and html files.) If you entered an image type as the MIME type, the uploaded image will be displayed on the Content page.

    Note:

    Text files (text/plain) uploaded to the Pagelet Producer must be saved as UTF-8.

  • Click the Save icon in the navigator toolbar.

After the file is uploaded, it will be available for use in injectors and pagelets at the following URL: http://<host_name>:<port_number>/pagelets/<resourcename>/<filepath>.

For example, if the file was uploaded under the "welcome_resource" resource and the name for the file was entered as "images/myimage.jpg" the path to the hosted file on the Pagelet Producer server would be: http://<host_name>:<port_number>/pagelets/welcome_resource/images/myimage.jpg

Keep the following in mind when working with hosted files:

  • The hosted file feature should not be used for bulky files.

  • If you choose to host OpenSocial gadget XML files, the files must be placed under an anonymous resource (with no security policy) or gadget functionality will not work correctly.

  • Hosted files cannot be created for WSRP or Oracle JPDK portlet producers.

25.9 Registering WSRP and Oracle JPDK Portlet Producers in the Pagelet Producer

The Pagelet Producer can expose WSRP and Oracle JPDK portlets as pagelets for use in Framework applications, Spaces, and third-party portals.

You can use Oracle Enterprise Manager, WLST or the Pagelet Producer Console to register a WSRP or Oracle JPDK endpoint as a portlet producer. After registration, a new Pagelet Producer resource is created and automatically populated with pagelets to represent the portlets associated with the WSRP endpoint.

For detailed instructions, see Chapter 24, "Managing Portlet Producers." To access portlet producer settings from the Pagelet Producer Console, select Producers from the dropdown menu in the navigator toolbar, then click Register.

25.9.1 Using WSRP and Oracle JPDK Portlets

Auto-generated WSRP and Oracle JPDK resources and pagelets cannot be modified. Primarily intended for initial testing, they are virtual entries and do not exist in Pagelet Producer metadata definitions.

To make changes and create a permanent reference to the producer, the auto-generated resource must be cloned. To create a version that can be modified, select the resource in the Pagelet Producer Console navigator, and click Clone. The cloned version of the resource can be edited, and various elements such as injectors can be added to customize pagelet functionality. Cloned resources are stable and will be included in metadata exports.

You can also define a portlet-based pagelet from scratch by creating a new resource based on an existing portlet producer and then creating individual pagelets. For details, see Section 25.4, "Creating Resources."

25.10 Managing Import, Export, Backup and Recovery of Pagelet Producer Components

The Pagelet Producer stores data related to its configuration and content in the Oracle metadata store (MDS) to facilitate disaster recovery and the full production life cycle from development through staging and production. This section describes the import, export and backup capabilities available.

For detailed information about MDS, see the chapter "Managing the Oracle Metadata Repository" in the Oracle Fusion Middleware Administrator's Guide.

25.10.1 Exporting and Importing Pagelet Producer Metadata Using WLST

The metadata created by the Pagelet Producer is stored in MDS and can be accessed using WLST. For detailed information on running WLST commands, see Section 1.13.3.1, "Running Oracle WebLogic Scripting Tool (WLST) Commands."

Only global migration is currently supported; all data in the source environment is included in the exported MDS package, and all data in the target environment is overwritten when the package is imported.

Note:

If you are migrating your WebCenter Portal implementation from staging to production, export and import of Pagelet Producer data is handled by the migration tool. However, if changes were made to Pagelet Producer objects in the staging environment, these changes must be migrated independently using the WLST commands described in this section. If the Pagelet Producer does not function after migration, check the Server URL defined for the Pagelet Producer in your WebCenter Portal application. For information on setting this URL, see Section 25.2, "Registering the Pagelet Producer." For details on WebCenter Portal migration, see Chapter 40, "Managing Export, Import, Backup, and Recovery of WebCenter Portal."

25.10.1.1 Exporting Pagelet Producer Metadata Using WLST

To export base documents for the Pagelet Producer, including any resources, pagelets and custom configuration settings, use the WLST command exportMetadata.

For example:

exportMetadata(application='pagelet-producer', server='WC_Portlet_Staging', toLocation='c:\work\myexport', docs='/**')

Where:

  • application: Name of the Pagelet Producer application for which the metadata is to be exported (for example, pagelet-producer).

  • server: Server on which the Pagelet Producer is deployed (for example, WC_PortletStaging).

  • toLocation: Target directory to which documents selected from the source partition are to be exported. The toLocation parameter can be used as a temporary file system for migrating metadata from one server to another.

  • docs: List of comma separated fully qualified document name(s) and/or document name patterns (* and ** patterns).

For detailed syntax and examples, see "exportMetadata" in Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

25.10.1.2 Importing Pagelet Producer Metadata Using WLST

To import Pagelet Producer metadata and customizations, use the WLST command importMetadata.

For example:

importMetadata(application='pagelet-producer', server='WC_Portlet_Production', fromLocation='c:\work\myexport', docs='/**')

Where:

  • application: Name of the Pagelet Producer application for which the metadata is be imported (for example, pagelet-producer).

  • server: Name of the target server on which the Pagelet Producer is deployed (for example, WC_Portlet_Production).

  • fromLocation: Source directory from which documents are imported. The fromLocation parameter can be any temporary file system location for migrating metadata from one server to another.

  • docs: List of comma separated fully qualified document name(s) and/or document name patterns (* and ** patterns).

For detailed syntax and examples, see "importMetadata" in Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

Note:

Any environment-specific URLs used in object configuration must be updated manually after import.

25.10.2 Backing Up and Restoring the Pagelet Producer

Backup and recovery operations for the Pagelet Producer are part of standard MDS backup and restoration and can be managed through database export and import utilities, and various other tools. For detailed information, see "Part IV Advanced Administration: Backup and Recovery" in Oracle Fusion Middleware Administrator's Guide.

By default, the MDS configuration for Pagelet Producer is as follows (from adf-config.xml):

<metadata-store name="PageletProducerMetadataRepos" class-name="oracle.mds.persistence.stores.db.DBMetadataStore">
  <property name="partition-name" value="pageletproducer"/>  <property name="jndi-datasource" value="jdbc/mds/PageletProducerDS"/>
  <property name="repository-name" value="mds-PageletProducerDS"/> </metadata-store>

25.11 Troubleshooting Pagelets

Keep the following common configuration errors in mind when troubleshooting resources and pagelets. For details on configuring Pagelet Producer settings, see Section 25.3, "Configuring Pagelet Producer Settings."

  • If you are using SSL, make sure both HTTP (nonsecure) and HTTPS (secure) ports are configured properly on the Transform page of the Pagelet Producer settings.

  • If you are proxying external sites on a network that requires an HTTP proxy, you must configure the proxy URL on the Proxy page of the Pagelet Producer settings.

  • Confirm that the login_resource and pagelet_api resources, created by default, are present and correctly configured.

  • If you are proxying KD Browser or other CSP pagelets, make sure the image service URL is absolute and the CSP SOAP API URL is set correctly in the CSP page of the Pagelet Producer settings.

  • Due to restrictions in the Sun Java Virtual Machine (JVM), pagelets cannot use HTTPS content where the underlying certificate uses MD2 signing algorithm.

For additional troubleshooting information, use logging. The Pagelet Producer logs messages to the standard Oracle Diagnostic Logging facility. In Oracle WebLogic Server, that location is: user-projects/domains/<domain>/servers/ <server>/logs/<server>-diagnostic.log. For details on configuring logging, see Section 25.3.1, "Logging Settings." For more information on debugging pagelets, see Creating Pagelets with Oracle WebCenter Portal's Pagelet Producer in the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter Portal

25.11.1 Redeploying the Pagelet Producer to a Different Context

In some cases, the default web context defined for the Pagelet Producer may need to be changed. This section describes how to redeploy the Pagelet Producer to a different context.

The first step is to target the Pagelet Producer data source to the Administration Server and locate the Pagelet Producer EAR file. In Oracle WebLogic Server:

  1. In the Oracle WebLogic Server Console, go to Services > Data Source.

  2. Click on the mds-PageletProducerDS data source.

  3. Go to the Targets tab.

  4. Check the box next to AdminServer and click Save.

  5. Navigate to Deployments/pagelet-producer.

  6. If Oracle Enterprise Manager is running on the same host as Pagelet Producer, record the path to the EAR file. If Oracle Enterprise Manager is on a different host than Pagelet Producer, copy the EAR file from the Pagelet Producer host machine to the browser host machine.

Next, use Oracle Enterprise Manager to redefine the context:

  1. Navigate to (Application) Deployments/pagelet-producer.

  2. From the Application Deployment Menu, select Application Deployment > Undeploy and follow any prompts that appear. Click Undeploy.

  3. From the Weblogic Domain menu, select Application Deployment > Deploy.

  4. Set the Archive location to the Pagelet Producer EAR file (located and/or copied in the first set of steps above).

    • If Oracle Enterprise Manager is running on the same host as the Pagelet Producer, select the second option and browse to the EAR file location.

    • If Oracle Enterprise Manager is on a different host than Pagelet Producer, select the first option, and click Choose File to select the EAR file from the location it was copied to on the browser host machine.

  5. Select WC_Portlet.

  6. Change the Context Root of the Web Modules as follows, where "new_context" is the web context that should be used (to redeploy to root, omit "new_context"):

    • ensemblestatic.war: new_context/ensemblestatic

    • pageletadmin.war: new_context/admin

    • opensocial.war: new_context/os

    • loginserver.war: new_context/loginserver

    • ensembleproxy.war: new_context/

    Note:

    OpenSocial pagelets will not function properly if the Pagelet Producer is deployed to root context.

  7. Click Deploy.

If your implementation uses OpenSocial, update the context setting in the Pagelet Producer Console. For details, see Section 25.3.6, "OpenSocial Settings."