The Oracle WebCenter Pagelet Producer (previously called Oracle WebCenter Ensemble) provides a collection of useful tools and features that facilitate dynamic pagelet development. The Oracle WebCenter Pagelet Producer proxy provides users with external access to internal resources including login resources, internal applications, and pagelets.
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 also take advantage of many of the features available to portlet developers to write pagelets that are parameterized and configurable, to dynamically interact with other pagelets, and respond to user input using Asynchronous Javascript and XML (AJAX) patterns.
This chapter describes how to register, edit, delete, and deploy pagelets using the Pagelet Producer Console.
This chapter includes the following sections:
Section 24.1, "What You Should Know About the Oracle WebCenter Pagelet Producer"
Section 24.4, "Creating Pagelet Producer Resources and Pagelets"
The content of this chapter is intended for Fusion Middleware administrators (users granted the Admin or Operator role through the Oracle WebLogic Server Administration Console). For more information, see Section 1.13, "Oracle WebCenter Administration Tools."
Consider the following while working with the Oracle WebCenter Pagelet Producer:
Resources are web applications registered with the Pagelet Producer. Registering 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.
Data can be passed to pagelets using pagelet parameters or the pagelet payload. The former passes name-value pairs (attributes) to the pagelet application, while the latter is any text, including XML.
All post deployment connection configuration is stored in the Oracle Metadata Services (MDS) repository. For more information, see Section 1.3.5, "WebCenter Configuration Considerations." For detailed information about MDS, see the chapter "Managing the Oracle Metadata Repository" in the Oracle Fusion Middleware Administrator's Guide.
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 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
Pagelet Producer registration is dynamic. Additions and updates to existing producers are immediately available; it is not necessary to restart the WebCenter application or the managed server.
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.
This section describes how to register the Pagelet Producer using Fusion Middleware Control and WLST commands. This section includes the following subsections:
To register the Pagelet Producer:
Log in to Fusion Middleware Control and navigate to the home page for your WebCenter application. For more information, see:
Do one of the following:
For WebCenter Portal applications - From the Application Deployment menu, choose WebCenter, then Register Producer.
For WebCenter Spaces - From the WebCenter menu, choose Register Producer.
Enter connection details for the Pagelet Producer (Table 24-1).
Table 24-1 Pagelet Producer Connection Parameters
| Field | Description |
|---|---|
|
Connection Name |
Enter a unique name to identify this pagelet producer within the WebCenter application. The name must be unique across all WebCenter connection types. |
|
Producer Type |
Select Pagelet Producer. |
|
Server URL |
Enter the URL of the WebCenter Pagelet Producer. The URL must include a fully-qualified domain name. Use the following syntax:
For example:
If pagelets contain secure data, the registered URL must use the https://myhost.com:7779/ Note: In WebCenter 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 |
Click OK.
The new producer appears in the connection table.
Use the registerPageletProducer command to register a Pagelet Producer for your WebCenter 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.
Note:
When importing and exporting data using WLST, the resources.xml and settings.xml files must reside in a directory called "ensemble" and no other files may be present in that directory. The argument passed to the import/export commands should be the parent directory of the /ensemble directory.For information on how to run WLST commands, see Section 1.13.3.1, "Running Oracle WebLogic Scripting Tool (WLST) Commands."
This section describes how to set up the Pagelet Producer for use as a service by Oracle WebCenter using the Oracle Configuration Wizard.
For information about developing and deploying pagelets, see the section "Creating Pagelets with the Oracle WebCenter Pagelet Producer" in the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter.
To set up Oracle WebCenter Pagelet Producer as a WebCenter service:
Launch the Configuration Wizard (Oracle Fusion Middleware > Oracle WebLogic Server > Tools > Configuration Wizard).
Select Create a new WebLogic Domain. Click Next.
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.
Complete the domain configuration wizard. For details on specific settings, see the online help.
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 and pagelets, manage proxy and transformation settings, and more.
To launch the Pagelet Producer Console, open a browser window and navigate to http://host_name:port_number/pageletadmin/ and log on with the administrator name and password you entered when you created the domain using the Configuration wizard in Section 24.3, "Configuring the Pagelet Producer Service" in step 2. The pagelet producer console can also be launched in accessible mode at: http://host_name:port_number/pageletadmin/accessible.
From the Pagelet Producer Console, you can create resources and pagelets. To create a new resource, select the Resources option from the dropdown list, choose any existing resource in the navigation pane, and then click the Create icon in the toolbar. (This button is only enabled when you have selected an object type that can be created.)
An entry called "<new>" will be added to the list of resources, and it will include the necessary configuration pages, detailed in the sections that follow. To save your changes at any time, click the Save icon in the toolbar.
On the General page, enter basic information about the resource.
Enter a Name for the resource. Enter an optional Description.
In the Source URL field, type the URL to the internal web application 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 thanhttp://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 URL to be used to access the resource. This URL must be on the server that hosts the Pagelet Producer. In the Pagelet Producer URL space, you must specify a relative path at which the content must appear.
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.
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, choose 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.
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, choose 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.The Policy page allows you to limit access to a resource to specific roles within Oracle WebCenter. The J2EE container hosting 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 here must match those created in the Oracle WebLogic Server administrative Console.The Autologin page allows you to provide authentication information for a resource for use by all users who access the resource.
The autologin feature allows the Pagelet Producer to supply credentials to applications automatically. The credentials used by the Pagelet Producer to log in to the application can come from:
Credential vault: When a user logs into the proxied resource, credentials are stored in the Pagelet Producer credential vault. Subsequent access to that resource is authenticated using 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.
The user's LDAP profile: Credentials for specific applications can be stored in the user's profile and used by the Pagelet Producer to automatically log the user into proxied applications.
Static credentials: The Pagelet Producer resource can be configured with static credentials that are used for every user with access to the resource.
The Oracle WebCenter Pagelet Producer can automatically log in to resources through HTML forms and basic authentication.
The following sections describe how to configure credential mapping for authentication:
Section 24.4.4.1, "Form Login," describes how to configure a resource to log in automatically to a resource that prompts for authentication with an HTML form.
Section 24.4.4.2, "Basic Login and NTLM Login," describes how to configure a resource to log in automatically to a resource that prompts for authentication with basic or NTLM authentication.
Section 24.4.4.3, "Authentication Sources," describes the static, user profile, and credential vault authentication field sources.
This section describes how to configure autologin for a resource that prompts for authentication with an HTML form.
Note:
After defining the HTML form, make sure that sensitive fields are stored securely using the Credential Vault option.On the Autologin page for the resource, expand the Form Login section.
The login page can be identified by an URL or a regular expression. In the Login Form Identification section, choose 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.
Set the login form action. In the Form Submit Location section, choose one of the following options:
If the login form action is a static URL, select URL and type the URL into the box. Choose 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.
To map fields from the form to authentication field sources, either click Automatically Detect Form Fields or enter them manually using the process below:
Click Create to add a new row to the Form Fields list.
Type the name of the HTML form input in the Field Name box.
For details on how to configure the Source and Value properties, see Section 24.4.4.3, "Authentication Sources."
To delete field mappings, click Delete.
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, choose one of the following options:
If the page is located at a static URL, select URL and type the URL into the box.
If the page is dynamic, select RegEx and type the regular expression pattern into the box.
This section describes how to configure autologin for a resource that prompts for authentication with basic or NTLM authentication.
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.In the Username and Password sections, choose the appropriate authentication source and enter a value as necessary. For details on how to configure these properties, see the next section, Section 24.4.4.3, "Authentication Sources".
Authentication sources define the source for login fields. The following table describes each of the authentication field source values:
Table 24-2 Pagelet Producer Authentication Field Sources
| Field | Description |
|---|---|
|
Static |
Use the static source when the authentication field is the same for all users accessing the resource. Type the static value in the field provided. |
|
Profile |
The Profile source uses properties from the user's Oracle WebCenter profile to supply credential data for authentication. |
|
Vault |
he Vault source prompts the user for credentials the first time the resource is accessed. The supplied credentials are stored in the credential vault, and each subsequent access to that resource is authenticated with the stored credentials.In the second field, enter the name of the credential vault to use, or leave the entry as "default" to use the server vault. |
|
Shared Vault |
The same as the Vault option, except Vault stores one value per key per user, while Shared Vault stores one value per key for all users |
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. 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.
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.
The Pagelets section lists the pagelets associated with the resource.
To create a new pagelet, select the Pagelets section under the resource you want to use 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:
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.)
In the URL Suffix box, type the relative path to the pagelet (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.
If you want the pagelet to be refreshed without reloading the entire page, choose Refresh Inline.
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.
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 a Name for the pagelet and choose the Transport type: Request Parameter, Administrative Preference, Community Preference, or Pagelet Preference. Choose whether the parameter is Required and choose the appropriate data Type.
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.
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).
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 24.4.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.
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.
To create a new 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:
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 occurs by selecting one of the following:
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 entry provided in the field on the page.
Content to be injected may be any text, including HTML, CSS, JavaScript, and pagelet declarations. Content can be entered using the text editor. If the content is HTML, it can optionally be edited using the HTML editor.
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.Use Fragment Location to locate the part of the page that you wish to modify. Then you can use Fragment Type to choose how the selected location should be parsed.
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.
Make sure to choose the appropriate Fragment Type:
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.
The Oracle WebCenter Pagelet Producer can expose WSRP portlets as pagelets for use in WebCenter Portal applications, WebCenter Spaces, and third-party portals.
Note:
To use this feature, you must install patch 11809215 for Oracle WebCenter. Make sure to follow the instructions in the README file provided with the patch.You can use Enterprise Manager or the Pagelet Producer Console to register a WSRP endpoint as a portlet producer. After registration, the new producer is automatically populated with pagelets to represent the portlets associated with the WSRP endpoint.
Note:
The WSRP Producer cannot be within the same Oracle WebLogic Server instance as the Pagelet Producer.Register the WSRP endpoint using either Enterprise Manager or the Pagelet Producer Console.
In Enterprise Manager, go to the Pagelet Producer application. From the Application Deployment menu, click WebCenter > Register Producer.
In the Pagelet Producer Console, go to the Producers section and click Register.
In the Producer Type list, choose WSRP Producer and enter the URL to the WSDL for the WSRP endpoint.
If an HTTP proxy is required when contacting the producer, select the Use Proxy? option and enter the host name and port for the proxy server.
Enter a suitable timeout for communications with the producer. The default is 30 seconds.
If the producer requires authenticaion, select the appropriate token profile and enter any necessary configuration information.
To confirm that the configuration is correct, click Test.
If you registered the producer in Enterprise Manager, you must load the external registration in Pagelet Producer. Either restart the Pagelet Producer server, or complete the following steps:
Open the Pagelet Producer Console and select Producers from the drop-down list.
Click Refresh, then click Save.
Once registration is complete, the WSRP producer will appear as a Resource in the Pagelet Producer Console, and the portlets associated with the WSRP endpoint will be listed in the Pagelets collection.
The settings and parameters for the new pagelets are based on the portlet definitions in the WSDL for the WSRP producer. If modifications are made to the WSRP portlets, refresh the producer registration to import the changes. WSRP-based pagelets can be used like any other pagelets.
Note:
Auto-generated resources and pagelets cannot be modified. To make changes to the WSRP-based pagelets, follow the steps in the next section, Section 24.5.1, "Using WSRP Producers."Auto-generated WSRP resources and pagelets cannot be modified. Primarily a convenience 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 WSRP producer, the auto-generated resource must be cloned. To create a version that can be modified, choose the resource and click Clone.
The cloned version of the resource can now 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.
In the Pagelet Producer Console, the Settings section provides access to important settings that affect all pagelets provided by the Pagelet Producer.
The Logging page allows you to set logging levels for individual Pagelet Producer components. Logging is 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.
The Proxy page includes HTTP proxy access configuration (URL, user name and password). This page also allows you to define a semicolon-separated list of URLs that will not be proxied (wildcards are allowed).
You must restart the Pagelet Producer after changing the proxy setting.
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 (useful for debugging, but should not be enabled in a production environment).
CSP is a platform-independent protocol based on the open standard of HTTP 1.1. CSP defines the syntax of communication between Oracle WebCenter Pagelet Producer and external resources. It also defines custom headers as well as outlines how services use HTTP to communicate and modify settings.
The CSP section 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.This page allows you to configure the Oracle WebCenter Interaction REST endpoint, SOAP API service, and image service.
Keep the following common errors in mind when troubleshooting pagelets:
Pagelet Producer logs messages to the standard Oracle Diagnostic Logging facility. On Oracle WebLogic Server, the logs are stored at domain/servers/server-name/logs/server-name-diagnostic.log.
If you are using SSL, make sure both HTTP and HTTPS ports are configured properly in Settings.
If you are proxying external sites on a network that requires an HTTP proxy, you must configure the proxy URL in Settings.
Due to restrictions in the Sun Java Virtual Machine (JVM), pagelets cannot HTTPS content where the underlying certificate uses MD2 signing algorithm.
The Login Resource and Pagelet REST API Resource, which are created by default, are present and correct.
If you are proxying KD Browser or other CSP pagelets, make sure the Image Server URL is absolute and the CSP SOAP API URL is set in Settings.