Building Portlet Services PegaRULES Process Commander ...

Building Portlet Services

PegaRULES Process Commander versions 5.1 and 5.2

© Copyright 2006 Pegasystems Inc., Cambridge, MA

All rights reserved.

This document and the software describe products and services of Pegasystems Inc. It may contain trade secrets and proprietary information. This information should not be disclosed to third parties unless otherwise provided for by a contract or business agreement with Pegasystems. This document and the software are protected by federal copyright law, international laws, and/or applicable treaties.

This document is current as of the date of publication only. Changes in the document may be made from time to time at the discretion of Pegasystems. This document remains the property of Pegasystems and must be returned to it upon request. This document does not imply any commitment to offer or deliver the products or services provided.

This document may include references to Pegasystems product features that have not been licensed by your company. If you have questions about whether a particular capability is included in your installation, please consult your Pegasystems service consultant.

For Pegasystems trademarks and registered trademarks, all rights are reserved. Other brand or product names are trademarks of their respective holders.

Although Pegasystems Inc. strives for accuracy in its publications, any publication may contain inaccuracies or typographical errors. This document could contain technical inaccuracies or typographical errors. Changes are periodically added to the information herein. Pegasystems Inc. may make improvements and/or changes in the information described herein at any time.

This document is the property of: Pegasystems Inc. 101 Main Street Cambridge, MA 02142-1590 (617) 374-9600, fax: (617) 374-9620 www.pega.com PegaRULES Process Commander Document: Building Portlet Services Software Version: 5.1 and 5.2 Posting Date: December 2006

Contents

Introduction...............................................................................................................2 Summary of Steps for Building Portlet Services.................................................3

The Portlet Service ...................................................................................................4 Rules and Data Objects for a Portlet Service .....................................................4 Architecture and Processing...............................................................................7 Deployment Files................................................................................................9 User Attributes and Multiple Portlets ..................................................................9 Session and Window State...............................................................................10 Data Mapping for Portlet Services....................................................................10 Authentication, Identification, Single Sign-On ..................................................11 Portlets and Access Groups .............................................................................15

Portlet Web Pages ..................................................................................................16 Writing JSR 168-Compliant HTML....................................................................17 Generating JSR 168-Compliant HTML.............................................................19 Portlet Help.......................................................................................................21 Calling HTML Stream Rules From Activities.....................................................21 Calling Activities from HTML Stream Rules......................................................22 Calling Process Commander Text or Image Files ............................................22 When to Use setSuppressShowMethod...........................................................24 HTML Stream Rules vs. HTML Fragment Rules ..............................................25 PegaPortlet Example........................................................................................25 SamplePortlet Example ....................................................................................28

Building a Portlet....................................................................................................32 Before You Begin .............................................................................................32 Configuration and Setup...................................................................................33 Plan the Portlet .................................................................................................33 Create an Application ID...................................................................................36 Create or Identify the Model User.....................................................................36 Configure PRPortletService..............................................................................36 Create or Identify the Class Rule and Properties .............................................37 Provide the Portlet Web Pages ........................................................................37 Create the Portlet Activities ..............................................................................38 Create a Service Package................................................................................39 Create a Portlet Service Rule ...........................................................................41 Generate the WAR File ....................................................................................43 Deploy the WAR File and Test the Portlet ........................................................44


Running the Samples.............................................................................................45 Configure the PegaPortlet Sample ...................................................................45 Configure the SamplePortlet Sample ...............................................................47 Deploy a Sample Portlet ...................................................................................49 Run a Sample Portlet .......................................................................................50

Troubleshooting .....................................................................................................51


Java Specification Request 168 (JSR 168) describes a Java Application Programming Interface (API) for portlets, the small web applications displayed by portal servers. The portlet integration interface in PegaRULES Process Commander supports the development and deployment of Process Commander portlets that are compliant with JSR 168 through the Rule-Service-Portlet service rule.

When you build a portlet that displays work items and makes flow processing available, you can use the Process Commander HTML generation feature to generate portlet-compliant HMTL for rendering portlet Web pages. If you want to display parts of the Process Commander user interface other than work objects, you must code the HTML for the portlet Web pages yourself.

This document describes the Process Commander portlet service, using simple examples to illustrate how to create portlets that display your Process Commander application.

This document contains the following sections:

■ Introduction

■ The Portlet Service

■ Portlet Web Pages

■ Building a Portlet

■ Running the Sample

■ Troubleshooting


Introduction Building Portlet Services is part of a package of materials that includes two sample portlets. The HTML that renders portlet Web pages must comply with the JSR 168 specification. The samples illustrate the two ways to provide the HTML markup for a Process Commander portlet.

■ The PegaPortlet example illustrates the easy way to provide HTML markup: let Process Commander generate portlet-compliant HTML in the harness, section, and flow action rules that belong to the flow whose work objects will be displayed in the portlet. This sample is included in the main Process Commander RuleSet, Pega-ProCom, as part of the PegaSample application.

■ The SamplePortlet sample is a proof-of-concept that illustrates how to provide HTML markup for a Process Commander portlet by coding the HTML yourself. This sample is located in the PegaSample-IntSvcs RuleSet.

Both samples make the worklist of a Process Commander user available in a portlet. However, if your portlet is to display work objects, be sure to use the method illustrated in the PegaPortlet example. After deploying one of the samples on your JSR 168-compliant portal server, log in to your portal server as the sampleuser and examine the work list.

The document and samples are intended for PegaRULES Process Commander system architects who are Web developers and who have experience with the JSR 168 API.

For information about JSR 168, see the specification at the following URL:

http://jcp.org/aboutJava/communityprocess/final/jsr168/index.html

See also the Sun Microsystems white paper at the following URL:

http://developers.sun.com/prodtech/portalserver/reference/techart/jsr168/pb_whitepaper.pdf

Before continuing with this document, it is recommended that you read the book PegaRULES Process Commander Integrating with External Systems for general information about service rules (Rule-Service-*). The book was shipped with your software and is also available on the Integration Services pages of the Pegasystems Support Network.

Before you implement your own portlet services, read this document and implement one or both samples on your PegaRULESProcess Commander system as training exercises.


http://developers.sun.com/prodtech/portalserver/reference/techart/jsr168/pb_whitepaper.pdf

Building Portlet Services — 0BIntroduction 3

Summary of Steps for Building Portlet Services The following is a summary of the general steps to follow when building portlet services for PegaRULES Process Commander:

1. Download the PortletAPI archive (JSR 168 Final Draft) from the Java Community Process Web site, extract the Java archive portlet.jar, and add the portlet.jar file to the Process Commander compile time and run time class paths. For help with this step, see the PDN article PRKB-20931 “About the Process Commander 5.1 Class Paths.”

2. Create Process Commander flows and select the portlet compliant option in the harness, section, and action rules. If you are planning to display something other than work items or provide access to functions other than flow processing, code HTML stream rules that use JSR 168-compliant HTML markup to display the Process Commander content you want to make accessible through the portlet.

3. Create HTML stream rules for the portlet home page and the portlet help.

4. Build activities that provide the content and processing for the portlet.

5. Create the rules and data objects that make up a portlet service.

6. Use the service package (instance of Data-Admin-ServicePackage) to generate the Web Application Archive file (WAR) that implements the portlet.

7. Deploy the portlet WAR file on your JSR 168-compliant portal server.


The Portlet Service The portlet service provides access to a portlet Web application that you create. Your portlet application gathers and processes content from Process Commander and displays the content and the processing results in a portlet window on a portal page in a Web browser.

The service package represents the portlet application, and the portlet service rule represents an individual portlet in the application. The service activity for a portlet service provides the home page — the first Web page that appears in the portlet on startup. Although it is typical to have one portlet service rule in a Process Commander portlet application, you can develop portlet applications that have more than one portlet.

This section describes the portlet service: its rules, data objects, processing, deployment files, initialization values, window and session state, and authentication. The following section describes how to generate or write the HTML for the portlet.

Rules and Data Objects for a Portlet Service A portlet service requires the standard list of rules and data objects for all service rules as described in Integrating with External Systems, with the addition of the following:

■ At least one HTML stream rule to render the home Web page for the portlet and one to provide the help topic. If your portlet displays something other than work items, you must create additional HTML stream rules to render the Web pages that are displayed in the portlet window.

■ Because a portal server manages the authentication for all the portlets in its portlet pool, a portlet service also requires several data objects that enable the Process Commander single sign-on feature.

Figure 1 describes the rules and data objects that implement a portlet service.

Item Purpose

Service package (Data-Admin-ServicePackage)

Represents a portlet application and serves as the container that bundles the other components for the service. After you create one or more portlet service rules, use the service package to generate the portlet Web Application Archive (.war) file that you deploy on the portal server.

Building Portlet Services — 1BThe Portlet Service 5

Item Purpose

Service rule (Rule-Service-Portlet)

Specifies user attribute parameters and calls the service activity, which provides the first Web page that is displayed on startup. Identifies the help activity for the portlet.

If your portlet application has more than one portlet service rule, be sure to provide the same user attribute values in each rule. For more information, see “User Attributes and Multiple Portlets” on page 9.

Service activity (Rule-Obj-Activity)

Gathers and processes the content for the first Web page (home page) displayed in the portlet window, and then calls an HTML stream rule to render the content on the page.

Help activity (Rule-Obj-Activity)

Calls an HTML stream rule that displays instructions (help) for using the portlet. This activity is invoked when a user clicks the help icon in the portlet window.

Additional activities (Rule-Obj-Activity)

Gather the content, perform processing, and call HTML stream rules that render portlet Web pages other than the first one, if necessary.

HTML stream rules (Rule-Obj-HTML)

Render the content into pages that are displayed in the portlet window. The code in these rules must be compliant with the JSR 168 specification.

If your portlet makes flow processing available and you use portlet-compliant harness, section, and action rules, you typically need only two HTML stream rules: one to render the home page and one to provide the portlet help. To make other kinds of Process Commander functions available, you code additional HTML stream rules that render the portlet Web pages.

For more information, see “Portlet Web Pages” on page 16.

Class rule and properties for the service activity (Rule-Obj-Class) (Rule-Obj-Property)

The service activity and help activity apply to this class rule. If the portlet posts form data to PegaRULES, the field-value pairs sent from the portlet must have matching properties in this class rule.


Item Purpose

HTML fragment rules (Rule-HTML-Fragment)

(Optional) Provides reusable blocks of HTML that can be used by the HTML stream rules. The portlet samples do not use any fragment rules.

Single sign-on data objects and rules

See Figure 3, page 13.

Figure 1. Summary of Rules and Data Objects in a Portlet Integration


Architecture and Processing You install a Process Commander portlet by deploying its WAR file on your portal server and then configuring the portal page to display it. When a user logs in to the portal server, the server displays it with all the other portlets on the user’s portal page.

Figure 2 illustrates the architecture of the portlet service.

Portal Server

Response = code forrendering portlet

Portletwindow

WARfile

Request = portlet URL

PegaRULESProcess

Commander

Data-Admin-ServicePackage

Rule-Service-Portlet

Service Activity

HTML Stream Rule

Clipboard

Page

Figure 2. Architecture of a Portlet Service


The following describes how a portlet service works:

1. A user opens a browser and logs in to the portal server.

2. The portal server consults the WAR files for all the portlets that appear on that user’s portal page and then invokes the Java class in the Process Commander portlet’s WAR file.

3. The portlet’s Java class constructs a URL appended with certain parameter/value pairs and a security token, including information about the identity of the portlet user. The URL specifies the PegaRULES Process Commander system and the name of the portlet service rule.

4. Process Commander processes and authenticates the request from the portlet Java class. It verifies the security token, maps the user to an Operator ID, and creates a requestor session.

5. Process Commander invokes the service rule (Rule-Service-Portlet) identified by the Java class.

6. The service rule invokes its service activity.

7. The service activity gathers the content for the first Web page in the portlet and then invokes an HTML stream rule to render that content.

8. The HTML stream rule executes, streaming JSR 168-compliant HTML markup back to the portlet Java class.

9. The portlet Java class parses the HTML for state information (window state and requestor ID) and then sets the portlet session context. The Java class sets the window state, sets a cookie with the requestor ID for the session, creates actionURLs if necessary, and then renders the first Web page in the portlet window on the portal page in the user’s browser.

10. Subsequent browser requests occur when the user clicks on an item that calls an actionURL. ActionURLs are handled by the portal server, which responds by calling the processAction() method in the portlet’s Java class and passing parameters to the method, if there are any. The portlet passes the parameters to Process Commander to complete the necessary processing. PegaRULES streams JSR 168-compliant HTML markup back to the portlet Java class and step 9 repeats.


Deployment Files After creating the service rule, use the service package to generate the deployment files for the portlet. The service package generates a Web Application Archive (WAR) file for the portlet. The WAR file contains the following items:

■ Portlet class — a Java class that extends the javax.portlet.GenericPortlet.class and implements the portlet interface for your portlet. This class implements the portlet modes View and Help. It does not implement the Edit portlet mode.

The service package generates one portlet Java class for each portlet service rule in the service package.

Note: If your application has more than one portlet, you must position each one individually on the appropriate portal page after you deploy your portlet application.

■ portlet.xml file — the portlet definition file for your portlet application. This file specifies the portlet initialization parameters and their values, including the user attributes used for authentication or identification.

■ web.xml file — the Web application deployment descriptor file for the PRPortletFileHelperServlet servlet. This servlet displays files that are located in the Process Commander rulebase as rules of type Rule-File-Text or Rule-File-Binary. For more information, see “Calling Process Commander Text or Image Files” on page 22.

User Attributes and Multiple Portlets As mentioned, the service package is the equivalent of the portlet application, and the portlet service rule is the portlet. Although the user identification/authentication parameters appear on the form for the portlet service rule, these parameters are used as initialization properties for the portlet session context.

The portlet session context is set once per portlet application. The first portlet rendered at run time sets the portlet context session with its initialization properties. The other portlets in the portlet application function within that portlet session context (see step 9 in “Architecture and Processing” on page 7).

If your portlet application has more than one portlet (service rule), be sure to enter the same values in each rule for the authentication properties so that the portlet session context set by the first portlet to be rendered is appropriate for all the other portlets.


Session and Window State A portlet has two kinds of transient state:

■ Session state — the state of the HTTP session that implements the connection between the portlet and Process Commander. The session state must be stateful. (The design of your portlet probably also requires the use of authentication. For information about authentication and portlets, see “Authentication, Identification, Single Sign-On” on page 11.)

You set the session state in two places: with the Processing Mode field in the PegaRULES service package, and in the HTML stream rule that displays the portlet on startup. For information, see “Setting State Information” on page 18.

■ Window state — the state of the portlet window that the portlet is displayed in. Window state can be minimized, maximized, or of normal size.

You set the default window state in the HTML stream rule that displays the portlet on startup. For information, see “Setting State Information” on page 18. The portal user can then change the window state by using the minimize and maximize buttons in the portlet window.

Data Mapping for Portlet Services Data mapping defines the relationships between parameter-value pairs in external systems and property-value pairs on Process Commander clipboard pages. Because the external system for a portlet service is the portlet Java class generated by Process Commander, the portlet and Process Commander communicate without the need for data mapping.

The portlet and Process Commander communicate through HTTP, which means that they use Process Commander stream processing. If your portlet posts form data to Process Commander, the portlet’s Java class appends the form data to the URL in field-value pairs. Process Commander automatically interprets the field-value pairs as property-value pairs and maps them to clipboard or parameter pages.

For information about stream processing, see the Application Developer Help system.


Authentication, Identification, Single Sign-On A portal server manages the authentication of its users. Therefore, when a Process Commander portlet is invoked, the user is already identified and there is no reason for that user to identify himself again to Process Commander. The user credentials and identity are available, but this data must be transferred from the portal server to Process Commander. The transfer of credentials is managed through the Process Commander single sign-on feature.

Single sign-on is implemented through the authentication service data object (Data-Admin-AuthService). For portlets, single sign-on is implemented by default through a standard portlet authentication service.

When you build portlets, you can use the standard portlet authentication service to manage the identification of the portlet users. To do so, change the default settings to values that are appropriate for your system and modify the authentication activities as necessary. Additionally, if you find that the portlet authentication service does not suffice for your design, you can configure your own single sign-on or authentication scheme.

This section describes how to use the single sign-on feature implemented for portlets through the standard portlet authentication service, PRPortletService. For information about configuring a custom authentication scheme or the single sign-on feature, see Authentication in PegaRULES Process Commander 5.1. It is posted on the Integration Services section of the Pegasystems support Network.

Single Sign-On Rules and Data Objects An authentication service named PRPortletService is available by default to manage single sign-on for your portlet users. When the portlet Java class sends the portlet URL to Process Commander, PRPortletService can receive the request. PRPortletService starts a session for the portlet user, authenticates the user, and logs in the user.

Figure 3 describes the rules, data objects, and properties that you use to configure PRPortletService to manage single sign-on for your portlets.


Item Purpose

PRPortletService, an authentication service (Data-Admin-AuthService)

Working as a copy of the PRServlet servlet, authenticates a user based on information provided in the URL posted to it. An authentication service can authenticate a user in one of two ways: by using Process Commander authentication activities or by connecting to an external directory server. PRPortletService uses authentication activities.

Because an authentication service works as a Web alias for PRServlet, a servlet alias definition must represent it in the Process Commander web.xml file so URLs can be posted to it. PRPortletService has such a servlet alias definition in the web.xml file.

To use PRPortletService, you specify the name of the Web alias rather than PRServlet in the URL field in the portlet service rule form.

Authentication Activities: PortletAuthenticationExample PortletAuthenticationTimeout Example

(Rule-Obj-Activity)

Applies to: Code-Security

Used to implement a custom authentication scheme. PRPortletService provides two authentication activities.

PortletAuthenticationExample examines the user credentials and creates a requestor session for the operator ID. PortletAuthenticationTimeoutExample manages the time-out settings for authentication attempts.

When configuring single sign-on for your portlets, you can modify these activities or create your own. If you create your own authentication activities, be sure that they apply to the Code-Security class rule.

Application ID (Data-Admin-AppID)

Provides a way to verify the security token that the portlet uses to identify itself to Process Commander. You specify the application ID in the service rule.

When the portlet Java class creates a URL for the portlet, the URL includes the name of the AppID instance and a security token built with the password. PRPortletService then uses the application ID to verify the security token.


Item Purpose

Operator ID: [email protected] (Data-Admin-Operator-ID)

Serves as the model user — a template to set up a requestor session and perhaps to create an operator ID for the requestor.

The authentication activity for PRPortletService uses a model user to construct an operator ID instance. If the portlet user already exists in the Process Commander rulebase, that user’s profile is used instead.

User Identifier Attribute (field in the Rule-Service-Portlet form)

Used to determine the external user attribute (from the portal server) that maps to the pyUserIdentifier property of the Data-Admin-Operator-ID data object in PegaRULES. It is used to provide the value of the operator ID.

For example, a typical value for a WebSphere portal server is user.business-info.online.email.

User Name Attribute (field in the Rule-Service-Portlet form)

Used to determine the external user attribute (from the portal server) that maps to the pyUserIName property of the Data-Admin-Operator-ID data object in PegaRULES. You can use it to display a user’s personal name in the portlet.

If you are using a portal server that implements the optional “User Information Attribute Names” section of the JSR 168 specification (as does WebSphere Portal Server), you can leave this field blank. In this case, the portlet creates the user’s name by concatenating the values for following three Platform for Privacy Preferences (P3P) 1.0 properties: user.name.given, user.name.middle, and user.name.family.

Figure 3. Summary of Single Sign-On Data Object and Rules for Portlets


PRPortletService Processing The following describes how the PRPortletService authentication service works:

1. A user opens a browser and logs in to the portal server.

2. The portal server consults the WAR files for all the portlets that appear on that user’s portal page. For the PegaRULES portlet, the portal server invokes the Java class in the portlet WAR file.

3. The portlet Java class constructs a URL for PRPortletService, which is specified as the URL for the portlet by the portal server. Appended to the URL as a query string are name/value pairs for the following items:

− Application ID

− User identifier (operator ID)

− User name

− Time the request was submitted

− Security token

− Cost center number, if one was specified in the service rule

− Name of the service rule

4. The PRPortletService Web alias routes the request to the PRPortletService authentication service.

5. The PRPortletService authentication service invokes the PortletAuthenticationExample activity.

6. The PortletAuthenticationExample activity does the following:

− Looks up the application ID. Uses the password from the application ID to verify the security token.

− Looks up the User ID and User Name values sent in with the URL.

− Loads the model user (which is named [email protected] by default).

− Creates a requestor ID for the portlet user based on the model user, fills in the user name and user ID fields with the values that were appended to the URL, and takes values for five additional properties (organization, division, org unti, work group, and access group) from the model user.

− Uses the PRAuthentication interface to authenticate the user. Then, creates a profile for the user. If a profile already exists for this user, uses that profile. Otherwise, creates the profile based on the model user.

− Calls the Rule-Service-Portlet.Run activity, which invokes the service activity for the portlet service rule.


When configuring portlets, you can modify the PRPortletService authentication activities, provide new ones, or even create and implement your own single sign-on mechanism if you need to. PRPortletService is provided so you can implement your portlets with minimal configuration steps.

Portlets and Access Groups As with all PegaRULES services, you specify an access group in the service package form. This access group is consulted when the portlet Java class passes the URL of the portlet to PRPortletService. The URL identifies the service package, and the service package uses its access group to determine the correct version of the service rule through rule resolution.

After the service rule is identified, the access group associated with the user’s ID determines the correct version of the service activity rule, service help activity, and HTML stream rules. For this reason, be sure that the access groups assigned to your portlet users have the RuleSets necessary to run the portlet successfully.


Portlet Web Pages Activities and HTML streams create the user interface for your portlets. The activities gather content and perform processing (on work items, for example). The HTML from harness, section, flow action, and HTML stream rules render the content into the Web pages that the portlet displays.

The first or home page that appears in the portlet at startup is created by the service activity and the HTML stream rule that it calls. To provide the other Web pages in the portlet, the stream rule that renders the home page calls additional activities that call harness rules or additional stream rules, and so on.

The markup in the HTML displayed in a portlet window must be compliant with the JSR 168 specification: for example, some tags are restricted, URLS are referenced differently than in standard HTML, and session state must be set. In general terms, portlet Web pages can use only elements that can be rendered in an HTML table cell.

Most Process Commander portlets display work items and make flow processing available. You ensure that the components of the flow are portlet-compliant by selecting the portlet-compliant option in the harness, section, and flow action rules. When you save the rules, Process Commander generates JSR 168-compliant HTML markup.

Other parts of the Process Commander user interface — for example, reports and rule creation forms — do not use JSR 168-compliant markup in version 4.2. If you want to display anything other than work items in a portlet, you must code the HTML for those Web pages yourself.

The following sections describe how to create portlet Web pages.

■ Writing JSR 168-Compliant HTML

■ Generating JSR 168-Compliant HTML

■ Portlet Help

■ Calling HTML Stream Rules From Activities

■ Calling Activities from HTML Stream Rules

■ Calling Process Commander Text or Image Files

■ When to Use setSuppressShowMethod

■ HTML Stream Rules vs. HTML Fragment Rules

■ PegaPortlet Example

■ SamplePortlet Example

Building Portlet Services — 2BPortlet Web Pages 17

Writing JSR 168-Compliant HTML The Pega-ProCom RuleSet provides two standard HTML stream rules that you can use for a portlet home page and portlet help: Code-Pega-List.PortletUserWorkList and Work-.PortletUserWorkListHelp. You can use these rules as they are or edit them as needed. Additionally, if you develop a Process Commander portlet that makes available something other than work objects and flow processing, you must provide additional HTML stream rules for the Web pages.

This section presents some general rules for writing or editing HTML stream rules or flow action rules for portlets. For a complete description of how to write JSR 168-compliant markup, see the specification at the following URL:


See also the white paper entitled Best Practices: Developing Portlets Using JSR 168 and WebSphere Portal V5.02 at the following URL:

http://www-106.ibm.com/developerworks/websphere/library/techarticles/0403_hepper/0403_hepper.html

Additionally, the IBM WebSphere Portal Server Developer’s Guide contains information about writing the markup for a portlet.

Note: In PegaRULES Process Commander, only the elements associated with flows and work items are JSR 168-compliant.

Restricted HTML Tags To comply with JSR 168, HTML code cannot contain any of the following tags:

■ base

■ body

■ iframe

■ frame

■ frameset

■ head

■ html

■ title


http://www-106.ibm.com/developerworks/websphere/library/techarticles/0403_hepper/0403_hepper

http://www-106.ibm.com/developerworks/websphere/library/techarticles/0403_hepper/0403_hepper


To comply with JSR 168, XHTML and XHTML-Basic code cannot contain any of the following tags:

■ base

■ body

■ iframe

■ head

■ html

■ title

Constructing URLs When referencing URLs, do not use <A HREF> tags with the literal (hard-coded) URL of the PegaRULES system. Instead, use the <PORTLETURL> tag. For example:

<form name="main" action="<PORTLETURL>" method="POST">

This tag instructs the portlet Java class to obtain an actionURL from the portal server. If form data is being posted to the portlet’s URL, the portlet Java class encodes and appends it as field-value pairs to the URL.

Setting State Information To comply with JSR 168, session state for the portlet must be set in the portlet session context. Window state can optionally be set in the portlet session context.

The Process Commander portlet service supports this requirement through the generated portlet Java class. The generated portlet Java class defines XML elements for session state and window state. You use these elements in your HTML stream rules to provide session and window state information to the Java class.

In the HTML stream rule that creates the home page, use the XML elements to provide session state information by setting the requestor session ID in a cookie and to provide window state information with the <windowstate> XML tag. For example:

{literal}

<PortletSession>

<windowstate>NORMAL</windowstate>

<cookie>{/literal}{pxRequestor.pxClientSession

normal}{literal}</cookie>

</PortletSession>

{/literal}


Generating JSR 168-Compliant HTML This section describes how to use the Process Commander HTML generation feature in the flow components to generate portlet-compliant HTML markup for your flows.

Harness Rules The HTML provided by a harness rule is generated by Process Commander when you save the rule. If the harness is for a flow that will be accessed through a portlet, select the Portlet compliant? option on the HTML tab of the harness rule. When you save the rule, Process Commander generates HTML that is compliant with the JSR 168 specification. It also determines whether the section rules, but not the flow action rules, referenced in the rule are also portlet-compliant. If any are not, it displays an error message.

Process Commander version 4.02 provides three new harness rules that you can use when developing a flow that is portlet-compliant:

■ PortletHarness — a template for new harness rules, configured to generate portlet-compliant HTML

■ SimpleConfirm — a portlet-compliant version of the Confirm harness rule used in the PegaPortlet sample

■ SimplePerform — a portlet-compliant version of the Perform harness rule used in the PegaPortlet sample

These rules apply to the Work- class rule.

Section Rules There are two ways to provide HTML for sections: either code it yourself or select the Auto-generate option on the HTML tab of the rule and have Process Commander generate it. However, when creating a portlet-compliant section rule, you must have Process Commander generate the code.

When you select the Portlet compliant option in a section rule, the Auto-generate option is selected by default. When you save the rule, Process Commander generates JSR 168-compliant HTML markup and verifies that any section rules referenced in the section rule are also portlet-compliant. If any are not, it displays an error message.

Process Commander provides six section rules that you can use when developing portlet-compliant harnesses:

■ PortletSection — a template for new section rules, configured to generate portlet-compliant HTML

■ SimpleAction — a portlet-compliant version of the Action section rule used in the PegaPortlet example


■ SimpleConfirm — a portlet-compliant version of the Confirm section rule used in the PegaPortlet example

■ SimpleCoreSummary — a portlet-compliant version of the CoreSummary section rule used in the PegaPortlet example

■ SimpleDetail — a portlet-compliant version of the Detail section rule used in the PegaPortlet example

■ SimpleHeader— a portlet-compliant version of the Header section rule used in the PegaPortlet example

These section rules apply to the Work- class rule.

Flow Action Rules As with section rules, there are two ways to provide the HTML for flow action rules: either code it yourself or select the Auto-generate option on the HTML tab of the rule and have Process Commander generate it. However, when creating a portlet-compliant flow action rule, you must have Process Commander generate the code.

When you select the Portlet compliant option in a flow action rule, the Auto-generate option is selected by default. When you save the rule, Process Commander generates JSR 168-compliant HTML markup. Process Commander version 4.02 provides a portlet-compliant flow action template that you can use when developing flows. It is named PortletAction, and it applies to the Work- class rule.

The flow action rules that will be used in a harness or section rule cannot be determined until runtime. Therefore, when developing a portlet, be sure to test every path through the flow in the portlet window to verify that each piece of the flow is portlet-compliant.

HTML Property Rules Process Commander does not offer an HTML generation option for HTML properties (instances of Rule-HTML-Property). For properties of this type, you code the HTML yourself. When you save a harness, section, or flow action rule that refers to an HTML property, Process Commander does not examine the HTML in the rule to determine whether it is compliant with JSR 168. Therefore, you must ensure that the HTML you use for an HTML property is JSR 168-compliant.


Preexisting Flow Rules If you decide to use a flow that was not originally designed to be displayed in a portlet, copy the flow. Then select each assignment shape and determine which harness it calls. Open the harness, select the HTML tab, select the portlet-compliant option and save the rule. Determine which section and flow action rules are referenced by the harness and make them portlet-compliant as well.

Portlet Help The HTML stream rule that provides the portlet help does not launch the PegaRULES Process Commander Application Developer Help system. Instead, the rule provides help information for using the portlet window. To see an example, open the HTML stream rule PegaSample-Task.PortletUserWorkListHelp.

Calling HTML Stream Rules From Activities The service activity and help activity call HTML stream rules that provide the portlet’s home Web page and help page. The PegaProCom RuleSet provides two standard HTML stream rules that you can use for portlets: Code-Pega-List.PortletUserWorkList and Work-.PortletUserWorkListHelp.

To call an HTML stream rule from an activity, use the Show-HTML activity method and specify the name of the stream rule in the HTML Stream field. For example, Figure 4 shows how the service activity for the PegaPortlet example calls the PortletUserWorkList stream rule.

Figure 4. Using the Show-HTML Activity Method


Calling Activities from HTML Stream Rules HTML stream rules can also call activities. To call an activity from an HTML stream rule, use name/value pairs for the pyActivity property and the two-part key to the activity name.

For an example, open the Code-Pega-List.PortletUserWorklist HTML stream rule. When this HTML is rendered in the portlet window, it displays the user’s worklist. Each item in the list provides a link to that work item.

The following code calls the activity that calls the flow for the work object:

<input type="hidden" name="pyActivity" value="Assign-

.ProcessAssignment">

With Process Commander harness development, you are allowed to post name/value pairs for both the pyActivity and the pyStream properties. For portlet development, however, the best practice is to use pyActivity only.

Calling Process Commander Text or Image Files Text and image files can be stored in the Process Commander rulebase as instances of Rule-File-Text or Rule-File-Binary rather than as static files on a Web server. To locate and serve Process Commander files on portlet pages, the portlet uses a servlet named PRPortletFileHelperServlet. To indicate that a file is a Process Commander file that should be handled by the PRPortletFileHelperServlet servlet, use the ContextURL parameter.

ContextURL and PRPortletFileHelperServlet When the portlet invokes a Process Commander activity, the portlet Java class constructs a URL to the Process Commander system with several name/value pairs appended to it (including the name of the activity). One of these parameters is ContextURL, which holds the value of the absolute URL to the web context for the portlet web application.

The portlet web.xml file maps the URL of the portlet web application to the PRPortletFileHelperServlet servlet. Therefore, when a file is referenced with the value of ContextURL prepended to its name, PRPortletFileHelperServlet processes the request and then locates and displays the file.


Using ContextURL To call a Rule-File-Text or Binary file from HTML stream rules that are not used in portlets, you use a standard <IMG SRC> tag and reference the file by using the values from the following properties: Relative Path, File Name (second key to the rule), File Type (third key). For example:

<IMG SRC= “images/activitybanner.gif”>

When referencing an instance of Rule-File-Text or Rule-File-Binary in an HTML stream rule that is used by a portlet, insert the ContextURL parameter before the name of the file. To continue with the previous example, for the activitybanner.gif file to appear on a portlet page, you would modify the IMG SRC syntax as follows:

<IMG SRC= “{param.ContextURL}images/activitybanner.gif”>

ContextURL and the Parameter Page The ContextURL parameter is located on the parameter page of the activity that the portlet called. If the activity that calls an HTML stream rule with a reference to the ContextURL parameter is not the same activity that was called by the portlet, you must make the value of the ContextURL parameter available by copying it to the clipboard.

For example, a portlet calls ActivityA. ActivityA sets the value of ContextURL to a property named PortletURL on page named PortletPage and then calls ActivityB. ActivityB calls the Show-HTML method for an HTML stream that calls the activitybanner.gif file from our previous examples. Now the IMG SRC markup would look like this:

<IMG SRC= “{PortletPage.PortletURL}images/activitybanner.gif”>


When to Use setSuppressShowMethod Everything that appears in the Process Commander user interface is rendered by the HTML in a harness rule. At some point, most of the standard Process Commander activities call a harness rule to display the results of their processing. At that point, Process Commander does the following:

1. Determines whether the requestor is a portlet user. (Portlet requestor IDs start with the letter P.)

2. If the requestor is a portlet user, examines the harness to determine whether it is portlet-compliant.

3. Does one of the following:

− If the harness is portlet-compliant, streams the HTML from the harness to the portlet.

− If the harness is not portlet-compliant, streams back an error message such as this one:

When you create a portlet that makes available work objects and flow processing, you make the flow’s harnesses, sections, and flow action portlet-compliant. For other parts of the Process Commander user interface, you must substitute your own portlet-compliant HTML in place of the standard HTML stream that displays that part of the user interface.

When a standard Process Commander activity is called, the activity displays the results by making a Show-HMTL call to its standard HTML stream. To substitute your own portlet-compliant code, you must suppress the activity’s call to the standard stream. Otherwise, the non-compliant HTML markup cannot be rendered correctly by the portal server, and either an error message or a blank page is displayed in your portlet window.

To stop a standard Process Commander activity from displaying its HTML stream , use the setSuppressShowMethod method in a Java step in the activity that calls the Process Commander activity. For example, open the PegaSample-Task.PortletShowItemDetail activity. The first step is a Java step with the following code:

tools.getRequestor().setSuppressShowMethod(true);


The second step uses the Call activity method to call the Assign-Worklist.ProcessAssignment activity. Because the HTML is suppressed by the setSuppressMethod Java method, the ProcessAssignment activity returns data but does not call the normal harness (which means that Process Commander does not execute error-checking for a portlet user).

The third step is another Java step that disables the setSuppressShowMethod method as follows:

tools.getRequestor().setSuppressShowMethod(false);

The third step disables the method because the fifth and final step uses the Show-HTML activity method to call the PortletShowItemDetail HTML stream rule. This stream rule uses JSR 168-compliant markup to display the details of the work item.

For another example of when to use setSuppressShowMethod, see the PegaSample-Task.PortletFinishAssignment activity.

HTML Stream Rules vs. HTML Fragment Rules If your portlet design uses standard blocks of text that appear on more than one portlet Web page with content that does not depend on the values of properties or pertain to a specific class rule, you can use HTML fragment rules (Rule-HTML-Fragment). Remember that the Show-HTML activity method can call HTML stream rules, but cannot call HTML fragment rules. Therefore, fragment rules can be included in HTML stream rules with the INCLUDE directive, but fragment rules cannot be called from activities.

For more information about Rule-HTML-Fragment, see the Application Developer Help system.

PegaPortlet Example

The PegaPortlet sample, a portlet named WorkList, displays a user’s work list in a portlet window on a portal server. This sample is designed to provide flow processing for work objects that use the PegaSample-SimpleTask flow named SimpleProcess. All the components of the SimpleProcess flow are portlet-compliant.

Figure 5 shows WorkList in the upper left corner of a sample portal page.


Figure 5. Portal Page with the WorkList Portlet Sample

The service activity, Work-.PortletUserWorkList, creates the home page. It extracts the user’s work assignments from the database and uses the Code-Pega-List.PortletUserWorkList HTML stream rule to display the assignments in a list. When the user clicks on an item, the Assign-.ProcessAssignment activity is called. This is a standard Process Commander activity that loads the work object and the flow and calls the appropriate harness to display the work object.


Because the SimpleProcess flow uses portlet-compliant HTML streams , the action window appears, as shown in Figure 6.

Figure 6. Action Window for WorkList Portlet Sample

Although the home page of the PegaPortlet WorkList portlet gathers and lists all the user’s assignments, the portlet is designed to work only with work objects that use the PegaSample-SimpleTask flow. If you select an item that uses another flow, the portlet displays an appropriate error message. For example, if a harness in that flow is not portlet-compliant, the following message appears:

The following is a list of the activities and HTML stream rules in the PegaPortlet portlet service:

■ Service activity: Work-.PortletUserWorkList

■ HTML stream rule for the home page: Code-Pega-List.PortletUserWorkList

■ Help activity: Work-.PortletUserWorkListHelp

■ HTML stream rule for the help: Work-.PortletUserWorkListHelp

The HTML that renders the subsequent Web pages for PegaPortlet comes from the PegaSample-SimpleTask flow (SimpleProcess). Its harnesses, sections, and flow actions are portlet-compliant.


SamplePortlet Example As does the PegaPortal sample, the SamplePortlet sample (MyWorkList) also displays a user’s work list in a portlet window on your portal server. However, this portlet illustrates how to create a portlet application from scratch, without using generated HTML markup from Process Commander. Figure 7 shows MyWorkList in the upper-left corner of a sample portal page.

Figure 7. Portal Page with the My Worklist Portlet Sample


The service activity, PortletUserWorkList, creates the home page. It extracts the user’s work assignments from the database and then invokes the PortletUserWorkList HTML stream rule to display the items in a list. When the user clicks an item, the PortletShowItemDetail activity displays the details about that item in a new Web page as shown in Figure 8:

Figure 8. Details Window for My WorkList Portlet Sample

The PortletShowItemDetail activity calls the Assign-Worklist.ProcessAssignment activity (a standard Process Commander flow activity) and then invokes the PortletShowItemDetail HTML stream rule to display the web page.

PortletShowItemDetail displays the individual work item in a page like the one in Figure 8. If the item is locked, it calls the ActionLocked HTML stream rule to display a message that the item is locked. Otherwise, it uses the ActionNone HTML stream rule to display a message under the action selection list.

If you select an action from the selection list, another Web page appears, depending on the action you selected. The page is created by the PortletSelectAction activity, which identifies the action you selected and then calls either the ActionApprove or the ActionReject HTML stream rule, as appropriate. For example, Figure 9 shows the Web page that appears when you select the approve action.


Figure 9. Approve Window for My WorkList Portlet Sample

When you click the Submit button, the PortletFinishAssignment activity is called. The PortletFinishAssignment activity calls the Work-.FinishAssignment activity to process the item and then calls the Conf HTML stream rule. Figure 10 shows the confirmation message the Conf stream rule creates.

Figure 10. Confirmation Message for My WorkList Portlet Sample


The following is a list of the activities used in the MyWorkList portlet:

■ Service activity: PegaSample-Task.PortletUserWorkList

■ Help activity: PegaSample-Task.PortletUserWorkListHelp

■ Additional portlet activities:

− @baseclass.PortletShowItemDetail

− PegaSample-Task.PortletSelectAction

− PegaSample-Task.PortletFinishAssignment

− PegaSample-Task.PortletCleanupWorkItem

■ Process Commander activities:

− Assign-Worklist.ProcessAssignment

− Work-.FinishAssignment

The following is a list of the HTML stream rules used in the MyWorkList portlet:

■ @baseclass.PortletUserWorkList

■ @baseclass.PortletUserWorkListHelp

■ PegaSample-Task.PortletShowItemDetail

■ PegaSample-Task.ActionApprove

■ PegaSample-Task.ActionLocked

■ PegaSample-Task.ActionNone

■ PegaSample-Task.ActionReject

■ PegaSample-Task.Conf


Building a Portlet This section describes how to create a portlet service and uses the PegaPortlet sample to illustrate each step. This document does not describe every field on every form. For help or information about a field that is not defined in this document, see the Application Developer Help system.

To create a Process Commander portlet, complete the following tasks:

■ Before You Begin

■ Configuration and Setup

■ Plan the Portlet

■ Create an Application ID

■ Create or Identify the Model User

■ Configure PRPortletService

■ Create or Identify the Class Rule and Properties

■ Create the HTML Stream Rules

■ Create the Portlet Activities

■ Create a Service Package

■ Create a Portlet Service Rule

■ Generate the WAR File

■ Deploy the WAR File and Test the Portlet

Before You Begin Before you begin, complete the following tasks:

■ Verify that you have a JSR 168-compliant portal server installed and running, and that you are allowed to deploy the portlet on it.

■ Examine the authentication scheme for your portal server. Determine the names of the user attributes on the portal server that represent the UserIdentifier and UserName properties in the Process Commander Data-Admin-Operator-ID class rule. Make a note of the names of these properties.

Building Portlet Services — 3BBuilding a Portlet 33

Configuration and Setup To set up Process Commander so that it can generate portlet WAR files, you must obtain and install the portlet.jar file. Complete the following steps:

1. Download the PortletAPI archive, JSR 168 Final Draft from the Java Community Process web site:


2. Extract the archive and locate the portlet.jar file.

3. Go to the PDN (http://pdn.pega.com) and locate PRKB-20931 “About the Process Commander 5.1 Class Paths.”

4. Follow the instructions in that document to add the portlet.jar file to the Process Commander compile time and run time class paths.

Plan the Portlet During the planning stage, determine which Process Commander functions and gadgets the portlet will make available. Then plan the layout: determine the activities you need to do the processing and the flows and/or HTML stream rules you need to display the portlet Web pages. For more information, see “Portlet Web Pages” on page 16.

Determine which class rules and properties are pertinent for your portlet activities, choose names for each part of the portlet service, and use Figure 11 and Figure 12 to keep track of the names.

For reference purposes, the middle column of Figure 11 and Figure 12 lists the names of each item used in the portlet service samples. Write the names of the data objects and rules you create in the remaining column. Choose meaningful, explanatory names.


http://pdn.pega.com


Portlet Part Portlet Samples Your Portlet Project

RuleSet PegaPortlet: Pega-ProCom

SamplePortlet: PegaSample-IntSvcs

RuleSet version Pega-Procom: 05-01-20

PegaSample-IntSvcs: 05-01-06

Access group PegaPortlet: PegaRULES:PortalUser

SamplePortlet: [email protected]

Class rule for service activity, help activity, and HTML stream rules

PegaPortlet: Work- and Code-Pega-List

SamplePortlet: PegaSample-Task, and @baseclass

Service activity name

PegaPortlet: Work-PortletUserWorkList

SamplePortlet: PegaSample-Task.PortletUserWorkList

HTML stream rule for service activity

PegaPortlet: Code-Pega-List.PortletUserWorkList

SamplePortlet: @baseclass.PortletUserWorkList

Help activity name PegaPortlet: Work-.PortletUserWorkListHelp

SamplePortlet: PegaSample-Task.PortletUserWorkListHelp

HTML stream rule for help activity

PegaPortlet: Work-.PortletUserWorkListHelp

SamplePortlet: PegaSample-Task.PortletUserWorkListHelp


Portlet Part Portlet Samples Your Portlet Project

Service package name

PegaPortlet

SamplePortlet

Service class name PegaPortlet: ProcessWork

SamplePortlet: Sample

Service method name

PegaPortlet: WorkList

SamplePortlet: MyWorkList

Figure 11. Rule and Data Object Names for Your Portlet Service

Examine the authentication scheme for your portal server. Identify the names of the user attributes on the portal server that represent the UserIdentifier and UserName properties in the PegaRULES Data-Admin-Operator-ID class rule. Choose a name for an application ID. Write down the names for the authentication details in Figure 12.

Single Sign-On Item

Portlet Samples Your Portlet Project

Authentication service

PRPortletService PRPortletService

App ID PegaPortlet: PortalServer

SamplePortlet: PortletSampleApp

User Identifier attribute

Both samples: user.business-info.online.email

User Name attribute

Not specified

Model User Both samples: [email protected]

Figure 12. Names of Single Sign-On Items


Create an Application ID To create an application ID for your portlet application, create an instance of the Data-Admin-AppID data object. In the New form, use the name you chose during the planning stage (see Figure 12).

If you need help filling out the AppID form, see the Application Developer Help system or Authentication in PegaRULES Process Commander 5.1.

Create or Identify the Model User By default, the authentication activity for the PRPortletService authentication service uses a model user with the operator ID [email protected]. Examine this operator ID to determine whether it will work as a model user for your portlet. If it does not, create a new operator ID (Data-Admin-Operator-ID) or identify an operator ID that can be used as the model user.

If you need help to create an operator ID (Data-Admin-Operator-ID), see the Application Developer Help system or Administration and Security.

Configure PRPortletService The PRPortletService authentication service is available to provide single sign-on capability for your portlet users. You can modify the authentication activities or use a different model user to meet your requirements.

PRPortletService uses two activities:

■ Code-Security.PortletAuthenticationExample

■ Code-Security.PortletAuthenticationTimeoutExample

Open and examine the PortletAuthenticationExample activity. Modify it as necessary for your system requirements. For example, if you cannot use [email protected] as the model user, expand step 5 and change the operator ID of the model user. If you decide to modify the activity further or to provide your own authentication activity, remember that at a minimum, the activity must log in the portlet user.

Open and examine the PortletAuthenticationTimeoutExample activity, and then modify it if needed.


Create or Identify the Class Rule and Properties During the planning stage, you identified the class rule and properties for the portlet activities. If the class rule or any of the properties do not exist, create them.

Because a portlet typically makes an existing gadget available, it is unlikely that you must create a new class rule for the portlet activities and stream rules. The portlet activities apply to the class rule with properties that the activities manipulate and process. For example, because the SamplePortlet example displays a work list of tasks from a flow that applies to the PegaSample-Task class rule, the majority of the portlet activities apply to the PortletSample-Task class rule.

Provide the Portlet Web Pages As mentioned, the first or home page in the portlet is created by the service activity and the HTML stream rule that it calls. During the planning stage, you decided how you would produce the portlet W eb pages. Are you using a portlet-compliant flow? Are you coding it all yourself?

Create the HTML Stream Rules Based on your plan, write the HTML stream rules. You must create at least two: one for the main or home page and one for the portlet help. These rules typically apply to the same class rule as the portlet activities, with some exceptions. For example, when an activity extracts a list with the Obj-List method, the list is placed on a clipboard page of type Code-Pega-List. Therefore, for the PegaPortlet example, the HTML stream rule that the service activity calls is Code-Pega-List.PortletUserWorkList rather than Work-.PortletUserWorkList.

For information about writing HMTL rules for portlets, see “Writing JSR 168-Compliant HTML” on page 17. See also the standard Process Commander HTML stream rules for portlets (Code-Pega-List.PortletUserWorkList and Work-.PortletUserWorkListHelp) and the stream rules in the SamplePortlet example.

Verify the HTML Streams from the Flows are Portlet-Compliant If your portlet displays a worklist, verify that the HTML streams used by the flows are portlet-compliant. Open the flow, select each assignment shape, and verify that the harness, section, and flow action rules are portlet-compliant.


Create the Portlet Activities During the planning stage, you determined how many portlet activities the portlet needs. Create the following kinds of activities for the portlet:

■ A service activity that gathers the data to be displayed on the home page and then invokes the HTML stream rule that renders the data into a Web page.

■ A help activity that displays help for the portlet.

■ If your portlet displays anything other than a worklist, you may need additional activities that provide the content for the other Web pages.

Because you specify the name of the service activity and help activity when you create the service rule, you must create the service activity and the help activity before you create the service rule.

To create a portlet activity, complete the following steps:

1. From the Rules by Type explorer, select Technical > Activity.

2. Click New.

3. In the New form, complete the fields as shown in Figure 13.

Field Selection

Applies to Enter the name of the Process Commander class rule that you chose for the service activity during the planning stage (see Figure 11).

For example, the class rule for most of the portlet activities for the SamplePortlet sample is PegaSample-Task.

Name Enter the name that you chose for the service activity in the planning stage (see Figure 11).

For example, the name of the service activity for the SamplePortlet portlet is PortletUserWorkList.

Figure 13. Fields in the New Window for a Service Activity


4. In the Activity form, on the Pages and Classes tab, configure a page for any of the class rules the activity interacts with.

5. On the Steps tab, create steps that implement the processing and functions for the purpose of the activity. If you need help, examine the sample portlet activities.

6. On the Security tab, accept the default settings.

7. On the History tab, enter a description in both the Full Description and the Usage fields.

8. Click Save.

9. Repeat this procedure for all the portlet activities you need to create.

Create a Service Package Complete the following steps to create a service package:

1. From the Integration page, under Resources, select Service Packages.

2. Click New.

3. In the New form, in the Service Package name field, enter the name that you chose for the service package in your planning stage (see Figure 11). For example, the service package in the portlet service examples are PegaPortlet and SamplePortlet.

4. In the Service Package form, on the Context tab, complete the fields as shown in Figure 14.

Field Value

Processing Mode Select Stateful.

Access Group Enter the name of the access group that you chose during the planning stage (see Figure 11).

Requires authentication? Select this box if the portal users are authenticated.

Suppress Show-HTML Do not select this option. For information about suppressing non-compliant markup on a case-by-case basis, see “When to Use setSuppressShowMethod” on page 24.

Figure 14. Fields on the Context Tab of the Service Package Form


5. On the Methods tab, click Service Type and select Rulet-Service-Portlet.


7. Click Save.

Note: Ignore the Deployment tab for now. You cannot use the Deployment tab to generate the WAR file for your portlet until you have created the service rule.

When you click the Show Service Methods button on the Methods tab, the service package displays a list of the service rules that are associated with the service package. Until you define a service rule for the service package, the list is empty, as shown in Figure 15.

Figure 15. Service Methods Field Before the Service Rule Exists.

However, you must create the service package before you can create the service rule because the service package name is the first key of the three-key value that identifies the service rule. When you return to the service package after you create the service rule, the service package displays a message similar to the one in Figure 16.

Figure 16. The Service Methods Field After the Service Rule Exists


Create a Portlet Service Rule Now that the service package, service activity, and help activity exist, you can create the service rule. Complete the following steps:

1. From the Rules by Type explorer, select Integration-Services > Service Portlet.

2. Click New.

3. In the New form, complete the fields as shown in Figure 17.

Field Value

Customer Package Name Enter the name of the service package you created for this service.

For example, the service packages for the service examples are PegaPortlet and SamplePortlet.

Customer Class Name Enter the name that you chose for the service class in the planning stage (see Figure 11). Note that this name is not the name of a Rule-Obj-Class rule.

For example, the service class name for the PegaPortlet example is ProcessWork.

Portlet Name Enter the name that you chose for the portlet in the planning stage (see Figure 11).

For example, the portlet name for the PegaPortlet example is WorkList.

Figure 17. Fields in the New Form for a Service Rule

4. In the Service Rule form on the Portlet tab, complete the fields as shown in Figure 18.

Field Value

Activity Class Select the class rule that corresponds to the page that will serve as the primary page of the service activity that you select in the Service Activity Name field.

For example, the Activity Class for the SamplePortlet service rule is PegaSample-Task. The Activity Class for the PegaPortlet service rule is Work-.


Field Value

Service Activity Name Enter the name of the service activity that you created for this service.

For example, the name of the service activity for both example portlet services is PortletUserWorkList.

Help Activity Name Enter the name of the help activity that you created for this service.

For example, the name of the help activity for both example portlet services is PortletUserWorkListHelp.

Application ID Enter the name of the application ID that you created for this portlet.

Cost Center Number Leave blank. (This field is for backward compatibility with previous single sign-on mechanisms.)

User Identifier Attribute Enter the name of the user attribute on the portal server that represents the UserIdentifer property of the Data-Admin-Operator-ID class rule. For example, a typical choice for WebSphere portal servers is user.business-info.online.email.

User Name Attribute (Optional) Enter the name of the user attribute on the portal server that represents the UserName property of the Data-Admin-Operator-ID class rule.

Figure 18. Fields on the Service Tab for a Portlet Service Rule

Figure 19 shows the Portlet tab for the PegaPortlet service rule, named PegaPortlet.ProcessWork.WorkList.


Figure 19. Portlet Tab for the PegaPortlet Portlet Service Rule


6. Click Save.

Generate the WAR File After you create the portlet service rule for your portlet, return to the service package and generate the WAR file for the portal application.

1. Open the service package that you created for the portlet service. For example, the sample portlet service packages are PegaPortlet and PortletSample.

2. Click the Show Methods button to verify that the service rule exists.

3. Select the Deployment tab.

4. In the Deployment Type field, select JSR-168.

5. In the Service Class field, select the service class name that you used for your portlet service rules. For example, the service class names for the portlet service examples are ProcessWork and Sample.

6. Click Generate Deployment Files. The Java compiler generates the portlet application files and creates the portlet’s WAR file. It stores the WAR in a directory at the top level of the Process Commander Web application, and displays the location of the file.


7. Make a note of the location of the WAR file so that you can deploy it on the portal server.

Note: If any of the portlet initialization parameters change after you have deployed the WAR file, you can modify the values in the portlet.xml file located on the portal server. You do not need to edit the service rule, regenerate the WAR file, and then deploy the regenerated WAR.

Deploy the WAR File and Test the Portlet To test the portlet, you must install it on the portal server and use it.

1. Follow the instructions from your portal server vendor for installing (deploying) portlets.

2. In the administrator interface of the portal server, configure the portlet’s PRPCConnectionURL property to set the URL of the portlet. Be sure to use the PRPortletService web mapping rather than PRServlet in the URL. For example: http://serverX:8080/prweb/PRPortletService.

3. Add the portlet to a portal page. Remember that if there is more than one portlet in your portlet application, you must add each one separately to the portal page.

4. Configure a portal user to be a valid user of the portlet by entering a string in the User Identifier Attribute on the portal server that identifies a valid Process Commander user.

For example, assume that you are using a WebSphere portal server and you specified that the user.business-info.online.email portal attribute is the User Identifier Attribute in the portlet service rule. In this case, enter the same email address for the portal user as is entered for that user in their Process Commander operator ID.

5. Log in to the portal server as the portal user you created or identified, display the portal page in your browser, and examine your portlet. If it does not work correctly, see “Troubleshooting” section on page 51.

Building Portlet Services — 4BRunning the Samples 45

Running the Samples This section describes how to set up and run the portlet service samples. Do not deploy both samples at the same time. To work with both samples, deploy one and then remove it from the portal page before you deploy the other. Before you begin:

1. Complete the tasks in “Before You Begin” on page 32.

2. Complete the steps in “Configuration and Setup” on page 33.

Configure the PegaPortlet Sample The PegaPortlet example is located in the Pega-ProcCom RuleSet, one of the default Process Commander RuleSets. To run the PegaPortlet sample, you create a user and at least one work object of type PegaSample-SimpleTask; copy the Pegaportlet.ProcessWork.WorkList service rule into your RuleSet and then set the user attributes; edit the PegaRULES:PortalUser access group; and generate the portlet’s WAR file for your system. Then you deploy the WAR file on your portal server and run the sample.

Create Work Items Complete the following steps:

1. Create or identify a sample user who will have PegaSample-SimpleTask work items only in his or her work list.

Note: You cannot use the [email protected] user for the PegaPortlet example.

2. Log in to Process Commander as this user and create at least one work item of this type (PegaSample-SimpleTask). Do not complete the work items.

Copy the WorkList Service Rule Copy the WorkList service rule to your RuleSet and then set the user attributes so they are appropriate for your system.

1. Log in to Process Commander as an administrator user.


3. Select PegaPortlet.ProcessWork.WorkList.

4. Use the Save As function to copy it to your RuleSet.


5. Click in the User Identifier Attribute field and specify the external user attribute that maps to the UserIdentifier property of Data-Admin-Operator-ID.

6. (Optional) Click in the User Name Attribute field and specify the external user attribute that maps to the UserName property of Data-Admin-Operator-ID. If you are using WebSphere Portal Server, you can leave this field blank.

7. Save the rule. (Check the rule back in if you checked it out.)

Edit the PegaRULES:PortalUser Access Group Add your RuleSet to the access group assigned to the service package, PegaRULES:PortalUser:

1. From the Rules by Type explorer, select Security > Access Group.

2. Open [email protected].

3. At the top of the RuleSet list, add the RuleSet you copied the portlet service rule into.

4. Save the access group.

Generate the processwork.war file To generate the deployment files, complete the following steps:


2. Select PegaPortlet from the list.

3. Click the Show Methods button to verify that your service rule exists.



6. In the Service Class field, select the name of the service class you used when you copied the ProcessWork.WorkList service rule.

7. Click Generate Deployment Files. Process Commander creates the portlet WAR file that contains the necessary deployment descriptor and Java classes.

8. Click the link to the WAR file to download it to your computer. Note the location of the file so that you can identify it to the portal server during deployment.


9. Continue with “Deploy a Sample Portlet” on page 49.

Configure the SamplePortlet Sample To run the SamplePortlet example, you upload the PegaSample-IntSvcs RuleSet, run an activity that generates sample work items, edit the sample portlet service rule, and generate the portlet’s WAR file for your system. Then you deploy the WAR file on your portal server and run the sample.

Import the PegaSample-IntSvcs RuleSet Download the PegaSample-IntSvcs.zip file that matches your version of Process Commander from the Integration Services section of the PDN:

http://pdn.pega.com/DevNet/PRPCv5/IntegrationServices/intsvcs_Index.asp

Then complete the following steps:

1. From the menu, choose File > Import Archive.

2. In the Select Import Mode field, choose Local Zip File.

3. Click the Browse button next to the File Name field to choose the file.

4. Click Upload File. The wizard uploads the file to the Process Commander ServiceDirectory directory and displays the message File Uploaded Successfully.

5. In the Select Import Mode field, choose Zip File on Server.

6. From the list of files, choose the one you just uploaded. The wizard examines the file and displays several options.

7. Click Import. Process Commander processes the zip file. When it is finished, it displays a status message.

8. Log out of Process Commander and then log back in as the sample user:

− User ID: [email protected]

− Password: rules

Note: For help with the steps in this procedure, see PegaRULES Process Commander Administration and Security.

http://pdn.pega.com/DevNet/PRPCv5/IntegrationServices/intsvcs_Index.asp

mailto:[email protected]


Run the CreatePortletItems Activity The MyWorkList portlet sample displays a user’s worklist in the portlet. Because work items cannot be included in a RuleSet, you generate the work items for the portlet sample by running an activity named PegaSample-Task.CreatePortletItems.

Complete the following steps:

1. Open the PegaSample-Task.CreatePortletItems activity.

2. Click the Run button.

3. In the Run Rule window, under Test Page, select No Test Page.

4. In the Parameters section, click Execute.

5. When the activity completes processing, click the refresh button.

6. Click the Process Work tab and examine the list of work items assigned to you. (You must be logged in as sampleuser to see the work items.) Verify that the work items appear, as shown in Figure 20.

Figure 20. Work Items for the Sample User

Edit the Portlet Service Rule Open the portlet service rule and set the user attributes for your system.


2. Select SamplePortlet.Sample.MyWorkList from the list to open it.

3. Click in the User Identifier Attribute field and specify the external user attribute that maps to the UserIdentifier property of Data-Admin-Operator-ID.

4. (Optional) Click in the User Name Attribute field and specify the external user attribute that maps to the UserName property of Data-Admin-Operator-ID. If you are using WebSphere Portal Server, you can leave this field blank.

5. Save the rule. (Check the rule back in if you checked it out.)


Generate the sample.war file To generate the deployment files, complete the following steps:


2. Select SamplePortlet from the list to open it.

3. Click the Show Methods button to verify that your service rule exists.



6. In the Service Class field, select Sample.

7. Click Generate Deployment Files. Process Commander creates the portlet WAR file that contains the necessary deployment descriptor and Java classes.

8. Click the link to the WAR file to download it to your computer. Note the location of the file so that you can identify it to the portal server during deployment.

9. Continue with “Deploy a Sample Portlet.”

Deploy a Sample Portlet The last step is to deploy the portlet example on your JSR 168-compliant portal server. Complete the following tasks:

1. On the portal server, create a user with a valid ID in Process Comander:

− For the SamplePortlet example, this user must be [email protected]. The string “[email protected]” must be the value of the user attribute that you specified as the external user attribute that maps to the pyUserIdentifier property.

− For the PegaPortlet example, this user must be the one for whom you created PegaSample-SimpleTask work items.

2. Follow the instructions in your portal server documentation to deploy the portlet WAR file on the portal server. Remember that you cannot deploy both samples at the same time. If you have already deployed one of the samples, remove it before you deploy the other sample.


3. In the administrator interface of the portal server, configure the portlet’s PRPCConnectionURL property to set the URL of the portlet. Be sure to use the PRPortletService web mapping rather than PRServlet in the URL. For example: http://serverX:8080/prweb/PRPortletService.

4. Add the portlet to a portal page.

Run a Sample Portlet To run a portlet sample, log in to the portal server as the sample user and display the portal page. The SamplePortlet example MyWorkList appears as shown in Figure 21.

Figure 21. SamplePortlet Example, MyWorkList

The PegaPortlet example WorkList appears as shown in Figure 22.

Figure 22. PegaPortlet Example, WorkList

The location of the portlet on the page depends on where you put it when you added it to the portal page.

Building Portlet Services — 5BTroubleshooting 51

Troubleshooting If the portlet cannot successfully interact with Process Commander, the problem is typically in one of the following categories:

■ Errors in the HTML markup. Examine your HTML stream rules and look for the following:

− Ensure that there are no naming conflicts between your HTML elements or Javascripts and others that are rendered by other portlets on the portal page.

− Verify that whenever the markup requests an actionURL, it provides the name of an activity that you know will stream back JSR 168-compliant markup. When the portlet handles an actionURL but there is no activity specified, the portlet calls the default activity for the user. The default activity may call a harness that is not portlet-compliant.

− Verify that the harness, section, and flow action rules in the flows you are using with the portlet are portlet-compliant.

− Make sure that you are using the ContextURL parameter for Process Commander image and text files. See “Calling Process Commander Text or Image Files” on page 22.

■ Access privileges are insufficient. There are two possible causes:

− Verify that the access group specified by the service package gives access to the service rule.

− Verify that the user’s access group gives you access to all the rules the portlet service uses.

■ You did not create all the required components. Review “Building a Portlet” (starting on page 32) and verify that you created all the necessary rules.

■ The activities you wrote do not work properly.

■ You are using clipboard pages improperly. Examine the following fields and tabs to verify that the page names (and their class rules) are configured correctly:

− Page Name field on the Service tab of the service rule

− Pages and Classes tab of the service activity

− Page names in activity steps that use the Page-New method


■ The portal server is not configured properly. Perhaps the problem is with the portal server. Consider the following questions:

− Are there problems with authenticating the client as a user? Confirm that the portal server makes the appropriate user attributes available to the portlet.

− Are transient issues preventing the portlet from running? Confirm that the network connection between the portal server and the Process Commander system is up.

Portlet requestor IDs start with the letter P, so you can easily trace a portlet requestor session. Additionally, you can use the remote logging feature to track the activity of the portlet. See PegaRULES Process Commander Administration and Security for information about the Remote Logging feature and setting logging levels for individual rules. See Testing Services and Connectors (available on the PDN) for information about tracing service rules.

Date post:	07-Feb-2022
Category:	Documents
Upload:	others
View:	2 times
Download:	0 times

Building Portlet Services PegaRULES Process Commander ...

Documents