15 Creating Pagelet Producer Objects

Create and configure the various objects in a Pagelet Producer deployment, including resources, pagelets, Web injectors, parsers and hosted files.

As explained in Pagelet Producer Console, the Pagelet Producer Console is a browser-based administration tool used to create and manage the various objects in a Pagelet Producer deployment. This chapter describes the settings required for each type of object.

Topics:

15.1 Creating Resources

Resources are applications registered with Pagelet Producer. 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 15-1 Pagelet Producer Console - Create Resource

    Description of Figure 15-1 follows
    Description of "Figure 15-1 Pagelet Producer Console - Create Resource"

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

    • Web: Any standard web application

    • CSP: CSP portlet provider application (for use with Oracle WebCenter Interaction)

    • WSRP/JPDK: WSRP or Oracle PDK-Java portlet producers (before you create a resource of this type, register the associated producer as described in Managing the Pagelet Producer in Oracle Fusion Middleware Administering Oracle WebCenter Portal).

    • OpenSocial: OpenSocial Container

    Figure 15-2 Select Producer Type Dialog

    Description of Figure 15-2 follows
    Description of "Figure 15-2 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 the pagelets and other objects within the resource. For more information, refer to the following topics:

15.1.1 How to Configure Web and CSP Resources

This section describes how to configure web and CSP resources.

This section includes the following topics:

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

15.1.1.1 How to Configure General Settings

Use the General page (see Figure 15-3) to enter basic information about the resource.

Figure 15-3 Pagelet Producer Console: Resource - General Page

Description of Figure 15-3 follows
Description of "Figure 15-3 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, 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 Pagelet Producer.

  • 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.

  • To enable rewriting of DHTML through asynchronous Ajax calls select Asynchronous Rewriting.

15.1.1.2 How to Configure CSP settings

By default, the CSP login token is not passed to the proxied resource. To enable this feature, choose Send CSP Login Token. Note that the CSP page is only available for CSP resources.

15.1.1.3 How to Configure Policy Settings

The Policy page (see Figure 15-4) lets you limit access to a resource to specific roles within WebCenter Portal.

Figure 15-4 Pagelet Producer Console: Resource - Policy Page

Description of Figure 15-4 follows
Description of "Figure 15-4 Pagelet Producer Console: Resource - Policy Page"

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 on this page must match those created in the J2EE container (such as Oracle WebLogic Server).

15.1.1.4 How to Configure Autologin

The Autologin feature allows Pagelet Producer to supply credentials to applications automatically. The Autologin page (see Figure 15-5) lets you configure authentication information for all users who access the resource.

Figure 15-5 Pagelet Producer Console: Resource - Autologin Page

Description of Figure 15-5 follows
Description of "Figure 15-5 Pagelet Producer Console: Resource - Autologin Page"

The following sections describe how to configure credential mapping for authentication:

15.1.1.4.1 How to Configure Autologin: 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 (Figure 15-6).

    Figure 15-6 Autologin Page - Form Login

    Description of Figure 15-6 follows
    Description of "Figure 15-6 Autologin Page - Form Login"

  2. 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 enter the URL in the Value field. You can choose to Automatically Detect Form Fields on the page or enter them manually as described in step 4 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, 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.

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

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

    2. Enter 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 How to Configure Autologin: Authentication Sources.

      Note:

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

    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, choose 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.

15.1.1.4.2 How to Configure Autologin: 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, choose the appropriate authentication source and enter a value as necessary. For details on how to configure these properties, see How to Configure Autologin: Authentication Sources.

15.1.1.4.3 How to Configure Autologin: 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 Configuring Pagelet Producer Settings.

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

  2. 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, How to Configure Autologin: 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.)

15.1.1.4.4 How to Configure Autologin: Authentication Sources

Authentication sources define the source for login fields. Table 15-1describes each of the authentication field source values:

Table 15-1 Pagelet Producer Authentication Sources

Field Description

Unsecured

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

Secured

Uses the field value is entered by an administrator in the Pagelet Producer Administration Console. The value is stored in the Credential Vault and is shared among all users, including non-authenticated (anonymous) users. The field key is auto-generated and displayed as a read-only field in the Administration Console.

User 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. The field key is auto-generated and displayed as a read-only field in the Administration Console.In the second field, enter the name of the credential vault to use, or leave the entry as "default" to use the server vault.

Note: When you choose 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.

Generated

(Form Login only) The field value is taken from the backend server response markup.

15.1.1.5 How to Configure Headers

The Headers page (see Figure 15-7) lets you choose request and response headers that should be dropped from the HTTP that is provided by Pagelet Producer.

Figure 15-7 Pagelet Producer Console: Resource - Headers Page

Description of Figure 15-7 follows
Description of "Figure 15-7 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.

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

The Content-Length header is always implicitly dropped, because manipulating content during the proxying operation renders the content length invalid in almost all cases.

To add a header to the list, click Create and enter the header name in the field provided.

Once the web or CSP resource is defined, you can create pagelets and other objects. For more information, see the following topics:

15.1.2 How to Configure WSRP and Oracle PDK-Java Resources

This section describes how to configure WSRP/JPDK resources based on WSRP and Oracle PDK-Java portlet producers.

Note:

Before you can create a resource based on a WSRP or Oracle PDK-Java portlet producer, you must register the producer as described in Managing the Pagelet Producer in Oracle Fusion Middleware Administering Oracle WebCenter Portal.

This section includes the following subsections:

15.1.2.1 How to Configure General Settings

Use the General page to enter basic information about a WSRP or JPDK resource.

  • Choose the portlet producer type from the Portlet Producer dropdown list. This list is populated with the producers that have been registered as described in Managing the Pagelet Producer in Oracle Fusion Middleware Administering Oracle WebCenter Portal.

  • Enter a Name for the resource.

  • Enter a Description for the resource (optional).

15.1.2.2 How to Configure Policy Settings

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

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 on this page must match those created in the J2EE container (such as Oracle WebLogic Server).

Once the WSRP or JPDK resource is defined, you can create pagelets and Web injectors. See the following topics for more information:

15.1.3 How to Configure OpenSocial Resources (OpenSocial Gadget Producers)

This section describes how to configure OpenSocial resources based on OpenSocial gadget producers.

Note:

Configure Pagelet Producer for use with OpenSocial before creating an OpenSocial resource. For more information, see How to Configure OpenSocial Settings.

15.1.3.1 How to Configure General Settings

Use the General page to enter basic information about the resource.

  • Enter a Name for the resource.

  • Enter a Description for the resource (optional).

15.1.3.2 How to Configure Policy Settings

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

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 on this page must match those created in the J2EE container (such as Oracle WebLogic Server).

Once the OpenSocial resource is defined, you can create pagelets and files. Refer to the following topics for more information:

15.2 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.

Note:

Do not make updates to the seeded resources (welcome_resource, login_resource, and pagelet_api). These were not intended to be modified.

This section contains the following topics:

15.2.1 How to Configure General Settings

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).

  • 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 PDK-Java portlets, choose 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 PDK-Java 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 support for WSRP or Oracle PDK-Java portlets, see Working with Pagelet Chrome for WSRP and Oracle PDK-Java Portlets.

  • 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 How to Configure Parameters page will be populated with the gadget's user preferences.

    For more information on support for OpenSocial gadgets, see Working with OpenSocial Gadgets.

To block access to the pagelet, choose Disabled. If the pagelet is included on any pages, it will display a simple error message.

15.2.2 How to Configure Preferences

On the Preferences page (see Figure 15-8), 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 PDK-Java based pagelets.

Figure 15-8 Pagelet Producer Console: Pagelets - Preferences Page

Description of Figure 15-8 follows
Description of "Figure 15-8 Pagelet Producer Console: Pagelets - Preferences Page"

15.2.3 How to Configure Parameters

Data can be passed to pagelets using pagelet parameters. Parameters pass name-value pairs to the pagelet application as described below.

On the Parameters page (see Figure 15-9), enter the Parameters that should be passed to the pagelet.

To add a parameter, click Create.

  • Enter the Name of the parameter.

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

  • Choose the appropriate data Type: string or numeric.

  • Enter a Description (optional).

Figure 15-9 Pagelet Producer Console: Pagelets - Parameters Page

Description of Figure 15-9 follows
Description of "Figure 15-9 Pagelet Producer Console: Pagelets - Parameters Page"

15.2.4 How to Configure the Clipper

Clipping lets you create a pagelet by clipping a portion of a larger Web page in a proxied application. A news Web page, for example, may contain 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:

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 How to Configure Autologin. If you are using the vault to store credential values (see How to Configure Autologin: Authentication Sources), 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 more information about hosted files, see Creating Hosted Files.)

  • If the graphical clipper cannot be used (for example, if the page ID is not available), use the Advanced Clipper to define the page region to clip using a regular expression.

15.2.5 How to Access the Pagelet and Preference Editor

Use the Documentation page (see Figure 15-12) to display sample code with which to access the pagelet and preference editor using either JavaScript or the REST API.

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

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

15.3 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 can then be configured using the General and Content configuration pages as described in the following topics:

Note:

Do not make updates to the seeded resources (welcome_resource, login_resource, and pagelet_api). These were not intended to be modified.

15.3.1 How to Configure General Settings

Use the General page (see Figure 15-13) to configure basic settings for the injector.

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.

In the Inject Location section, define where in the resource's output the injection will be made in relation to a unique string. Enter the unique string in the field provided and choose Before, After or Replace to define where to put the content relative to the string. If you choose to replace the string, you can use the Enclose tag to replace both the string and the enclosing tag. You can choose to ignore the case of the string by selecting Ignore case.

Figure 15-13 Pagelet Producer Console: Injectors - General Page

Description of Figure 15-13 follows
Description of "Figure 15-13 Pagelet Producer Console: Injectors - General Page"

15.3.2 How to Inject Content

Use the Content page to define content to be injected using the injector. Content to be injected may be any text, including HTML, CSS, JavaScript, and pagelet declarations.

For example, the following code could be injected at the beginning of a page. The example registers a handler function with the page load event and then uses the handler to modify the page markup (by finding and hiding the header and footer).

<script type="text/javascript">
if (window.addEventListener) {
window.addEventListener('load', hideHeaderFooter, false);
} else if (document.attachEvent) {
window.attachEvent('onload', hideHeaderFooter);
}
function hideHeaderFooter() {
var header =null;
 //find the header table by class 
if (document.getElementsByClassName) {
header =document.getElementsByClassName('page_header')[0];
 }else {
//for older versions of IE
 var tables =document.getElementsByTagName('table');
 for (var table in tables) {
if (table.class =='page_header') {
header =table;
 break;
 }
}
}
if (header != null) {
header.style.display ='none';
 }
//now find and hide the footer (easier to find, since it has an id)
 var footer =document.getElementById('t23PageFooter');
 if (footer != null) {
footer.style.display ='none';
 }
}
</script>

15.4 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. Note that parsers cannot be created for WSRP or Oracle PDK-Java portlet producers or OpenSocial gadget producers.

Note:

Do not make updates to the seeded resources (welcome_resource, login_resource, and pagelet_api). These were not intended to be modified.

To create a custom parser, select the Parsers section under the resource you want to use and click the Create icon in the toolbar to display the Parser's General page (see Figure 15-14):

  • 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.

  • Choose 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 15-14 Pagelet Producer Console: Parsers - General Page

Description of Figure 15-14 follows
Description of "Figure 15-14 Pagelet Producer Console: Parsers - General Page"

For example, the regular expression XMLFile=(.*?)" would identify URLs to XML files defined within a tag, as in <embed src="/i/flashchart/anychart_5/swf/OracleAnyChart.swf?>XMLFile=http://apex.oracle.com/pls/apex/apex_util.flash?p=53557:1:74175370346201:FLOW_FLASH_CHART5_R45192463162785599619_en".

15.5 Creating Hosted Files

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.

Note:

Do not make updates to the seeded resources (welcome_resource, login_resource, and pagelet_api). These were not intended to be modified.

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 (see Figure 15-15), 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 15-15 Pagelet Producer Console: Files - General Page

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

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

    Click Upload 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 PDK-Java portlet producers.