JSP Stream Support

PegaRULES Process Commander v 5.2

 © Copyright 2006
Pegasystems Inc., Cambridge, MA
All rights reserved.

This document describes products and services of Pegasystems Inc. It may

contain trade secrets and proprietary information. The document and product are
protected by copyright and distributed under licenses restricting their use,
copying distribution, or transmittal in any form without prior written
authorization of Pegasystems Inc.

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

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

Phone: (617) 374-9600

Fax: (617) 374-9620
www.pega.com

PegaRULES Process Commander

Document: JSP Stream Support
Software Version 5.2
Updated: December 22, 2006
Contents

JSP Tag Functionality.........................................................................................1

Overview..............................................................................................................1
Target Audience ...........................................................................................1
PegaRULES JSP Tags.......................................................................................2
Manually Written Streams ............................................................................3
Form-Based Generated Streams.................................................................4
Converting a Rule From Pega Directives to JSP Tags .....................................6
PegaRULES “Pega” Directives....................................................................6
Conversion Overview ...................................................................................6
The Conversion Process..............................................................................7
Example – Converting to JSP tags....................................................... 9

Conversion Issues ..................................................................................... 10

Java API Differences........................................................................... 11

Pages & Classes issue ....................................................................... 13

Known Issues in PegaRULES JSP Stream Support...................................... 17

1. <pega:withTarget> Tag.................................................................. 17

2. Unable to mix java with other test cases ....................................... 17

3. Complex && and || logic................................................................. 18

4. Java methods ................................................................................. 19

5. <pega:include> Tag ....................................................................... 19

6. User-modifiable attributes of the <%@ page %> parameter........ 19

7. Operations not supported in JSP streams ..................................... 19

8. Mapping Inputs to Pages and Properties ....................................... 20

9. Rule-Obj-JSP deprecated.............................................................. 21
JSP Tags in the pegatag Library .....................................................................22
JSP Tag Notes........................................................................................... 22
The comment tag....................................................................................... 22
assert.......................................................................................................... 23
chart ........................................................................................................... 24
param................................................................................................... 26

choose........................................................................................................ 27
otherwise ............................................................................................. 27

when .................................................................................................... 28

forEach....................................................................................................... 28
getSaved.................................................................................................... 28
include........................................................................................................ 29
listView ....................................................................................................... 30
lookup......................................................................................................... 32
lookup - property value........................................................................ 32

key ....................................................................................................... 34

lookup - localized value of a property ................................................. 34

onlyonce..................................................................................................... 37
reference.................................................................................................... 38
save............................................................................................................ 41
url................................................................................................................ 42
option ................................................................................................... 42

when........................................................................................................... 43
withEmbedded........................................................................................... 45
withPage .................................................................................................... 46
withReference............................................................................................ 46
withTarget .................................................................................................. 47
Appendix: Directive Comparison - HTML Syntax vs. new JSP Syntax ........ 48
 JSP Tag Functionality

Overview
PegaRULES has a very generic approach to formatting text dynamically from run-time
contents in the system. This is called “Stream Processing” and is implemented by the
code generated for rules that derive from Rule-Stream. Examples of this class of rules
(sometimes called “streams”) include Rule-Obj-HTML, Rule-Obj-XML and Rule-Obj-Corr
(Correspondence). When PegaRULES was originally written, JSP was not yet a
standard in the Open Source community, but was just evolving. Therefore, PegaRULES
implemented its own functionality for creating dynamic content (the “Pega directives”).

JSP Version 1.2 functionality has now become the de-facto standard for text/html
formatting within Servlets in the Open Source world. By embracing this technology, the
PegaRULES engine is made immediately accessible to a broad audience of developers,
without requiring them to learn proprietary markup syntax for the HTML displays.
Performance is improved over the original implementation, and support for tracking
“referenced rules” has been enhanced.

Standard JSP functionality generates a servlet that will execute the JSP page. Within the
PegaRULES engine, the Open Source code for Apache Jasper v1.2 (as the JSP
compiler) is directly integrated with the PegaRULES engine to process the JSP pages that
are stored in Rules. The code generated by Jasper is then integrated into the Rules
Assembly execution architecture. The result is a best-of-breed solution that embraces the
open standards and extends them with the superior code management facilities of
PegaRULES Rules Assembly architecture, to provide a vehicle for people who already
have industry-standard knowledge to be able to use that knowledge in PegaRULES.

Target Audience
This document covers taking advantage of JSP tags within the PegaRULES Process
Commander technology. It is intended for developers who are already familiar with
authoring streams in PegaRULES Process Commander and who are also familiar with
standard JSP technology.

CONFIDENTIAL 1
 JSP Tag Functionality

PegaRULES JSP Tags

JSP tags are stored in a “library,” which is a .jar file separate from PegaRULES Process
Commander. The prefix of this library must be referenced in the JSP tag, along with the
tag itself. In addition, the tag may have attributes. Attributes are used to pass parameters
(such as the name of a property) into the tag. (See the section JSP Tags in the pegatag
Library for a list of all the tags and their attributes in the pega library.)

The Pegasystems custom tag library is referenced with the prefix pega. As an example,
one of the tags included in the Pega library is the Reference tag. Using the Reference tag
requires the following syntax:

<pega:reference name=“name of the value being referenced”/>

where
pega is the name of the prefix for this library, as defined in the JSP “taglib” directive
reference is the tag name
name is the attribute for the reference tag

NOTE: The reference tag also has an abbreviated form:

<p:r n=”name of the value being referenced”/>

where
p is the abbreviated form for “pega”
r is the abbreviated form for “reference”
n is the abbreviated form for “name”

Note also that the regular form and the abbreviated form cannot be
mixed: the abbreviated syntax cannot be used with the long version, nor
can the long version be used with the abbreviated version. As an
example, the following is not allowed:

<p:r name=”name of the value being referenced”/>

<pega:reference n=”name of the value being
referenced”/>

Only the reference tag may be abbreviated. (See the reference entry in
the JSP Tags section for more details.)

In PegaRULES Process Commander, streams can be created in two different ways:

• written directly by a developer
• generated automatically from form-based definitions authored by a developer

Type of Stream Example Rules Action(s) when Rule is

containing this type of saved
code
manually written Rule-Obj-HTML written HTML is compiled
Rule-HTML-Fragment
generated based on Rule-HTML-Harness HTML is generated from the
user input (form-based Rule-HTML-Section Rule form and then
generation) Rule-Obj-FlowAction compiled

CONFIDENTIAL 2
 JSP Tag Functionality

Manually Written Streams

For a basic display in PegaRULES, HTML may be typed directly into the Rule. For
example, a message may be displayed for the user, using the Organization and
Organizational Unit properties from the clipboard.

Text example:

the OrganizationUnit division of Organization

Using JSP tags, the reference to these properties on the Requestor page
(.pxOrganization and .pxOrgUnit on the page pxRequestor) would be written as
follows:

the <pega:reference name=”pxRequestor.pxOrgUnit”/> division of

<pega:reference name=”pxRequestor.pxOrganization”/>

This text was typed into a Rule-Obj-HTML form and saved. At the bottom of the page, the
Generate For field must be set to JSP, signifying the use of JSP tags.

When a Preview is run from this Rule (using the Preview button at the top of the screen),
the specified value on the clipboard is substituted for the directive and displayed in the
Preview window at the bottom of the screen:

CONFIDENTIAL 3
 JSP Tag Functionality

NOTE: If a JSP form is saved (in error) with the Generate For field set to HTML, the
system will assume that this is a Pega directive Rule and search for the “bracket”
directives during compilation. If no bracket directives are found (due to this being a JSP
Tag page), the system will not display an error, but will display only the text. (The JSP
tags are generated as text, but since the resulting text appears to be HTML, most of the
resulting text is not visibly displayed – it can be seen by viewing the HTML source):

Form-Based Generated Streams

There are a number of Rules where the stream content is automatically generated for the
user, rather than being entered directly. Some of these Rules, such as Rule-HTML-
Harness, generate the HTML and then display it on a read-only tab. Other Rules, such as
Rule-HTML-Section, allow editing of the HTML after it has been generated by the system.

For these Rules, the form must be completed and saved in order to generate the HTML
code, which will then be displayed on the HTML tab of the Rule.

CONFIDENTIAL 4
 JSP Tag Functionality

Important: As with the Rules where HTML source is typed in directly, the developer must
choose whether to generate the HTML using Pega directives or JSP tags. This choice is
made via a dropdown menu in the Generate For field on the HTML tab:

If JSP tags are desired, the Generate For field must be set to JSP before the form is
saved and the HTML is generated. Otherwise the default of HTML will be used, and the
necessary directives will be generated using Pega directives.

CONFIDENTIAL 5
 JSP Tag Functionality

Converting a Rule From Pega Directives to JSP

Tags
Important:

It is PegaRULES Best Practice to create streams using JSP tags. Developers should
no longer create streams using the legacy HTML directives; however, previously-
written HTML directive based streams will continue to work. A subsequent release will
remove support for HTML directive based streams entirely.

PegaRULES “Pega” Directives

For Process Commander versions prior to 4.2, there were constructs called Pega
directives which governed how the system’s stream generation facilities dynamically
assembled text.

These directives were written using braces (‘{‘ ‘}’), as in the following example:

<HTML>
text {.pyLabel} this referred to the primary page
{FOREACH .pxResults}
{.pyFirstName}
{.pyLastName}
{/FOREACH}

The FOREACH directive would iterate through the pages of the results and print out the
following:

text myLabel
John Jones
Sally Smith
Fred Farkel
etc.

The directives might be used in a form letter (generated from Rule-Obj-Corr):

Dear {.pyFirstName},

Greetings! You have . . .

While this facility was powerful and worked well, it was not industry standard. Therefore,
beginning with Release 4.2, PegaRULES has implemented the standard for HTML
directives: JSP tags and tag libraries.

Conversion Overview
As shown in the previous section, a Pega directive references properties (or other objects)
directly, using braces. While most of the functionality of directives is supported by JSP
tags, the syntax is quite different.

CONFIDENTIAL 6
 JSP Tag Functionality

There are a number of Rules which are shipped in the release with Pega directives.
These Rules function effectively, and for this release, may be left as Pega directives if the
customer desires. Customers may also have created their own HTML forms and
harnesses in prior versions of PegaRULES, when only the Pega directives were available.
These may also be left as Pega directives, or they may be converted to JSP tags.
However, the new JSP tags will become the dominant technology over the next few
releases; customers should begin moving toward this functionality for their directives. The
Pega directives will be phased out of the product.

The feature which controls this functionality is a drop-down box on the HTML rules which
is labelled Generate For. The two choices for this drop-down are:

• HTML (refers to the Pega directives)

• JSP

The Conversion Process

The conversion process starts with checking out the Rule to be converted. This displays
the Convert to JSP button on the HTML tab.

CONFIDENTIAL 7
 JSP Tag Functionality

For some rules, the HTML information and the Convert to JSP button will be located at
the bottom of the screen:

Clicking on the Convert to JSP button will translate the various HTML directives into JSP
tags.

IMPORTANT POINTS:

• Note that the automatic conversion process makes a “best effort” attempt at
converting the Pega directives. Not all of the possible Pega directives will
translate directly; there are some constructs which are not supported, and some
may not convert completely. If the conversion process returns no errors, the form
should have converted correctly. If errors are reported by the conversion
process, then the system has run into one of the conversion issues.

• Remember to save the rule after the conversion process is complete!

CONFIDENTIAL 8
 JSP Tag Functionality

Example – Converting to JSP tags

Below is an example of the code changes made when the Convert to JSP functionality is
run. Note that all the Pega directives are converted to JSP tags, and that the Java code
designation has changed.

Original HTML code generated for ListEditorTools-EditCopy (with Pega directives):

<a STYLE='cursor: hand; text-decoration : underline ; font-size : 7pt'

ONCLICK='insertRow("{$SAVE(ItemIndex)}")'
onmouseover='window.status="Insert a copy of this row into the table.
Remember to replace the unique keys with new values."'
onmouseout='window.status=""'>COPY</a>

{WHEN {% basePage().getMessagesAll().equals("") %}}

<a ONCLICK='editRow("{$SAVE(ItemIndex)}")' STYLE='CURSOR: hand ; font-

size : 7pt ; text-decoration : underline '
onmouseover='window.status="Edit the displayed properties of this
record (and obtain a lock)."'
onmouseout='window.status=""'>EDIT</a>

{ELSE}
<img src="images/rplock.gif" WIDTH='20' HEIGHT='20' BORDER='0'
alt="{% basePage().getMessagesAll() %}" id="PegaRULESErrorFlag"
onclick="editRow('{$SAVE(ItemIndex)}')"
onmouseover="window.status='Click to try and edit this record again
(the lock may have been cleared)'"
onmouseout="window.status=''">
{/WHEN}

CONFIDENTIAL 9
 JSP Tag Functionality

Code after Convert to JSP button is clicked:

<!--

Warnings Detected!

1: The basePage() method is no longer supported. Please update your code

to pegarules v4 standards.
--!>

<a STYLE='cursor: hand; text-decoration : underline ; font-size : 7pt'

ONCLICK='insertRow("<pega:reference name='$SAVE(ItemIndex)' mode="NORMAL"
/>")'
onmouseover='window.status="Insert a copy of this row into the table.
Remember to replace the unique keys with new values."'
onmouseout='window.status=""'>COPY</a>

<pega:choose>
<pega:when java='<%= basePage().getMessagesAll().equals("") %>'>

<a ONCLICK='editRow("<pega:reference name='$SAVE(ItemIndex)'

mode="NORMAL" />")' STYLE='CURSOR: hand ; font-size : 7pt ; text-
decoration : underline '
onmouseover='window.status="Edit the displayed properties of this
record (and obtain a lock)."'
onmouseout='window.status=""'>EDIT</a>

</pega:when>
<pega:otherwise>
<img src="images/rplock.gif" WIDTH='20' HEIGHT='20' BORDER='0'
alt="<%= basePage().getMessagesAll() %>" id="PegaRULESErrorFlag"
onclick="editRow('<pega:reference name='$SAVE(ItemIndex)'
mode="NORMAL" />')"
onmouseover="window.status='Click to try and edit this record again
(the lock may have been cleared)'"
onmouseout="window.status=''">
</pega:otherwise>
</pega:choose>

Conversion Issues
When converting existing “HTML”-generated rules to JSP tags, there are a number of
considerations. Process Commander provides a conversion function, which will
1
automatically handle most of the conversions from the Pega directives to JSP tags. The
next section, Known Issues, lists some of the issues where the automatic conversion will
not work.

The developer must be prepared for the following situations:

• Differences between v2 Java API and V3 Java API

• Pages & Classes information

1
Note that this does not mean that 80% of the rules will convert with no problems. It means that
80% of the code will convert without problems. There may be one or two issues with each rule; 80%
of the rule will convert, and the developer will have to fix the outstanding issues.

CONFIDENTIAL 10
 JSP Tag Functionality

Java API Differences

The legacy Pega “{java}” directive allow references to methods from the v2 Java API. The
JSP form of these tags only allow references to methods from the v3 Java API. Most of
these methods are automatically converted as well; the following list shows the conversion
from the v2 to the v3 API methods:

v2 Java API methods v3 Java API methods

appendFormatted tools.appendFormatted( )
appendString tools.appendString( )
appendURL tools.appendURL( )
getPrimaryPage tools.getPrimaryPage( )
inputEnabled tools.hasInputEnabled( )
inputWanted tools.useModeInput( )
saveValueGet tools.getSaveValue( )
saveValueSet tools.putSaveValue( )
targetName tools.getTargetName( )
targetSet tools.putTarget( )
targetValue tools.getTargetValue( )
thisName tools.getActiveName( )
thisSubscript tools.thisSubscript( )
thisValue tools.getActiveValue( )

Methods with multiple definitions

Not all methods had a direct conversion, however. Some of the old v2 API methods had
more than one definition. For example, the appendProperty method could be defined as
either:

public final void appendProperty(Property aProperty, String

aStreamSpec, boolean aWantInput)

public final void appendProperty(String aReference, String

aStreamSpec, boolean aWantInput)

The new v3 API contains only one appendProperty method:

public void appendProperty(ClipboardProperty aProperty,

String aStreamSpec, boolean aWantInput);

The system will not be able to tell how the developer would wish to make this conversion,
so it reports an error to alert the developer to make this determination:

The appendProperty() method is no longer supported. Please

use tools.appendProperty(ClipboardProperty aProperty, String
aStreamSpec, boolean aWantInput) instead.

The appendStream method has a similar issue. The old v2 API methods are as follows:

CONFIDENTIAL 11
 JSP Tag Functionality

public final void appendStream(byte aStreamType, String

aStreamName)

public final void appendStream(byte aStreamType, String

aStreamName, String aQualifier)

The v3 API method contains:

public void appendStream(StringMap aKeys);

Methods with no conversion mapping

Some of the v2 Java methods will no longer be available in the v3 Java API. The
following Java methods are no longer supported:

• appendLookup
• basePage
• basePagePush
• forEachPageInList
• getIdent
• getOpposite
• inputPermitted
• targetPush
• thisRef (use tools.getActive( ) instead)
• thisRefPush

When converting Rules to the new JSP syntax, if errors occur due to using the above
directives, the developer must go back and rewrite the problem Java section to use the
newer (supported) APIs listed above.

Example: basePage

As shown in the conversion example above (for ListEditorTools-EditCopy), there is an

issue with basePage. When the Convert to JSP button is clicked, the following
comment/message is displayed at the top of the code:

<!--

Warnings Detected!

1: The basePage() method is no longer supported. Please update your code

to pegarules v4 standards.
--!>

This error occurred because basePage was referenced in the code, and there is no direct
conversion for this v2 API Java method. The reference:

<img src="images/rplock.gif" WIDTH='20' HEIGHT='20' BORDER='0'

alt="<%= basePage().getMessagesAll() %>" id="PegaRULESErrorFlag"
onclick="editRow('<pega:reference name='$SAVE(ItemIndex)'

CONFIDENTIAL 12
 JSP Tag Functionality

was rewritten to:

<img src="images/rplock.gif" WIDTH='20' HEIGHT='20' BORDER='0'

alt="<%= tools.getPrimaryPage().getMessagesAll() %>"
id="PegaRULESErrorFlag"
onclick="editRow('<pega:reference name='$SAVE(ItemIndex)'

Once the developer rewrote the code to remove the basePage method and replace it with
tools.getPrimaryPage, the conversion finished without error.

Note that tools.getPrimaryPage may not be the correct new method in all cases (if it were,
it would have been coded to run automatically). In this example, the developer had
determined that it was the appropriate functionality to use.

Pages & Classes issue

The JSP tag functionality has stricter validation than the old Pega directives; validation is
done not only at runtime, but also at save time. One of the main validations is to check the
class of the page being referenced in the lookup. When specifying a page & property
reference, the developer must add the class information into the Pages & Classes
tab of the HTML Rule. If this is not added, an error will occur.

CONFIDENTIAL 13
 JSP Tag Functionality

Example: NewWorkTask

In this example, the rule NewWorkPage has been checked out and Convert to JSP was
clicked. The code conversion completed correctly, as evidenced by the Valid message.

CONFIDENTIAL 14
 JSP Tag Functionality

However, when the rule was saved, errors were displayed:

Error:

JspC failed:
com.pega.jasper.JasperException:<h3>jsp.error.tlv.invalid.page</h3><p>nul
l:Undefined reference pxRequestor.pxReqURI must be defined in
pages and classes </p> <p>pega:reference:pxRequestorpxReqURI is not
recognized as a valid property reference </p>
<p>null: Undefinedreference pxRequestor.pxCurrentWorkPool must be
defined in pages and classes</p>
<p>pega:reference:pxRequestorpxCurrentWorkPool is not recognized as a
valid property reference</p>

The error was stating that there were two JSP tag references where the page information
was not on the Pages & Classes tab:

• pxRequestor.pxReqURI
• pxRequestor.pxCurrentWorkPool

CONFIDENTIAL 15
 JSP Tag Functionality

In this case, both of these errors could be solved by putting one reference on the Pages &
Classes tab:

Once the pxRequestor page was added to this list, the rule could be saved and was
marked Valid.

CONFIDENTIAL 16
 JSP Tag Functionality

Known Issues in PegaRULES JSP Stream

Support
The following is a list of unsupported operations on JSP pages.

1. <pega:withTarget> Tag
<pega:withTarget=”.property”/>

The withTarget tag works in conjunction with the pega:select tag (future functionality) to
establish the selected option in the HTML select statement that the pega:select tag writes.

The withTarget tag has been added as a basis to support the pega:select tag when it is
implemented, and has no other functionality.

2. Unable to mix java with other test cases

It is not possible to use both “JAVA” syntax and “WHEN” test clauses within && or ||
statements.

Split up the when tag into multiple when tags. And statements should be nested, while or
statements will exist within the context of a <pega:choose> tag.

Incorrect AND statement

<pega:when test = “<%=

tools.getStepPage().getString(“pxObjClass”) == “Rule-Obj-JSP” %>
&& $input-enabled”>
</pega:when>

Correct AND statement

<pega:when java=”<%= tools.getStepPage().getString(“pxObjClass”)

== ‘Rule-Obj-JSP’ %>”>
<pega:when test=”$input-enabled”>
Execute these statements when “test” evaluates to
true
</pega:when>
</pega:when>

Incorrect OR statement

<pega:when test=”<%= tools.getStepPage().getString(“pxObjClass”)

== ‘Rule-Obj-JSP’ %> || $input-enabled” >
</pega:when>

CONFIDENTIAL 17
 JSP Tag Functionality

Correct OR statement
<pega:choose>
<pega:when java=”<%=
tools.getStepPage().getString(“pxObjClass”) == ‘Rule-Obj-JSP’
%>”>
Execute these statements when “test” evaluates to true
</pega:when>
<pega:when test=”$input-enabled” >
Execute these statements when “test” evaluates to true
</pega:when>
</pega:choose>

NOTE: The above example illustrates a simple approach. If the code that would be in the
when blocks is large or complex, the code would be difficult to maintain, as it exists in two
places. In this case, a better approach would be to have the choose clause set a Java
result boolean variable in each of the when clauses, and then have a standalone
pega:when which tests the result boolean and conditionally executes one copy of the
code:

<% boolean result = false; %>

<pega:choose>
<pega:when java=”<%=
tools.getStepPage().getString(“pxObjClass”) == ‘Rule-Obj-JSP’
%>”>
<% result = true; %>
</pega:when>
<pega:when test=”$input-enabled” >
<% result = true; %>
</pega:when>
</pega:choose>
<pega:when test= “<%=result%>”>
Execute these statements when “test” evaluates to
true
</pega:when>

3. Complex && and || logic

Complex && and || statements are not supported, such as statements with parentheses
which change the natural computation order of the binary operators:

<pega:when test=”((canProcess && $input-enabled) || $this:isScalar) &&

isAdministrator”>
</pega:when>

It is not possible to mix Pega tokens (such as $this, $mode-input, etc.) with Java
expressions. In order to include both in a script, replace the entire statement with Java
script, where any valid Java boolean expression may be used.

<%= tools.getActive() != null &&

tools.getActive().getString("pxObjClass") == "Rule-Obj-Activity"
%>.

CONFIDENTIAL 18
 JSP Tag Functionality

4. Java methods
Some of the Java methods available in Pega “{java}” directives will no longer be available
within Java scripting tags for JSP pages. (Please reference the Conversion Issues topic
in the Converting a Rule section of this document for a full list of the Java methods which
are no longer supported.)

When converting Rules to the new JSP syntax, if errors occur due to using the these
directives, the developer must go back and rewrite the problem Java section to use the
newer (supported) APIs, which are available from the PublicAPI interface.

5. <pega:include> Tag
In order to include common fragments of text in the JSP, save these fragments to the
RuleBase as instances of Rule-HTML-Fragment (or other appropriate classes descended
from Rule-Stream), and then use the <pega:include> tag to reference that Rule for
inclusion in the form.

PegaRULES Best Practices recommends that anything referenced by Rules must be

saved into the RuleBase. Do not use the JSP include, which can only refer to files in the
file system.

6. User-modifiable attributes of the <%@ page %> parameter

It is possible to add packages to the list provided by PegaRULES in the imports attribute.
Do not delete any of these packages provided by PegaRULES, as the system would no
longer compile.

All other attributes are either set by the PegaRULES implementation or are meaningless in
the Rules Assembly architecture in which JSP executes.

7. Operations not supported in JSP streams

Jasper implements several tags, some of which are not supported in PegaRULES:

<jsp:include/> Instead of using the <jsp> version of include, PegaRULES

recommends using the <pega:include> functionality. The
jsp:include functionality will look for data in the file system
outside of PegaRULES, whereas the pega:include tag accesses
data stored in the RuleBase.

<jsp:forward/> This tag forwards a request onto another JSP tag which would
not be included in the RuleBase. There is not yet a
<pega:forward/> tag available, but this will be added in a future
release.

CONFIDENTIAL 19
 JSP Tag Functionality

8. Mapping Inputs to Pages and Properties

In order for input fields (“textboxes”) on HTML-created forms to be able to set input values
in Process Commander properties, the HTML tags have to be bound to the page/property
references, so a translation of a particular textbox into a reference for that particular
property could occur. The page and property would have to be specified for each input
textbox on the form.

This binding was typically done in Rule-HTML-Property instances, which were then
referenced in the Rule-Obj-Property definition. When the Rule-HTML-Property was
executed as part of the Rule-Obj-Property, the HTML could assume that the property to
which the textbox was bound was the Rule-Obj-Property, and the page was the page
upon which the property was found.

Thus, the Pega directive streams supported the feature of dynamically inserting HTML tag
attributes to bind a particular input-type HTML tag to a page/property. In these cases, the
page and property references would not have to be explicitly defined, but would be added
at runtime. For example, if a developer was working with the collapsible textarea defined
by the Rule-HTML-Property TextAreaWithExpand, the reference could be:

<input type=”text” size=”40”>

At runtime, this would be converted to:

<input type=”text” size=”40” name=”$PpyWorkPage$ppyDescription”>

where the page was pyWorkPage, and the property name was .pyDescription.

JSP-based stream do not support this automatic addition. Instead, the author must
manually insert a reference tag, asking the runtime to provide the custom entry to map
that input to the active page and property. For example, the input above must be written
like the following to obtain the same behavior as before:

<input type=”text” size=”40” name=”<pega:reference name=”$this-name”>”>

CONFIDENTIAL 20
 JSP Tag Functionality

9. Rule-Obj-JSP deprecated
A new rule type, Rule-Obj-JSP, was created in Release 4.2. This rule has been
deprecated, and is no longer used.

Like the original stream rule, Rule-Obj-HTML, the new Rule-Obj-JSP was derived from
Rule-Stream, and HTML code may be typed directly into the Rule (as opposed to having it
generated). However, whereas the HTML code in Rule-Obj-HTML may contain either
Pega directives or JSP tags, the code in Rule-Obj-JSP may only contain JSP tags. (There
is no dropdown choice on the form.)

CONFIDENTIAL 21
 JSP Tags in the pegatag Library

JSP Tags in the pegatag Library

JSP Tag Notes

Note 1: For each of the name attributes, Java code may be substituted (example: <%=
tools.getProperty(nameOfProp) %> ), as long as the Java code evaluates to a string. The
syntax would be:

<pega:include name = “<%= tools.getProperty(nameOfProp) %>”

The “<%=” designation is standard JSP syntax, and not a part of the pega taglib.

Note 2: When a page containing JSP tags is saved, it is compiled. During this
compilation process, the classes, properties, and other objects will be validated. Any
property or rule referenced in the tags must exist at the time that the page is saved.
Furthermore, any page referenced in the tags must be defined in the pages and classes
tab.

Example:
the <pega:reference name=”pxRequestor.pxOrgUnit”/> division of
<pega:reference name=”pxRequestor.pxOrganization”/>

In this case, pxRequestor must be defined in the pages and classes tab. If a property is
referenced directly, it is assumed that the property exists in the class of the step page for
this rule. For example, <pega:reference name=”.pxOrgUnit”/> would mean that
this rule would have to exist with a pyClassName of Code-Pega-Requestor.

The comment tag

The Pega directives had a COMMENT tag:

{COMMENT}
This would be for developer's comments
{/COMMENT}

There is no comment tag per se in JSP, but there is a comment feature.

Example:
<%-- comment here --%>

NOTE: This is standard JSP syntax, and not a part of the pega taglib.

It is also possible to use the following HTML syntax for comments:

<!—This would be for developers comments -->

Note that the comment in this syntax would be sent to the browser, which adds load to the
network traffic. Therefore, unless the developer wants the comment to go to the browser,
the JSP comment structure should be used.

CONFIDENTIAL 22
 JSP Tags in the pegatag Library

assert
The assert tag will compare the name specified in the tag to the class name of the
current step page, and execute its body if they are equal.

Use to make processing more efficient when working with one or more concrete classes
and the Obj-List method.

Syntax

<pega:assert name = "classname">

HTML segment
</pega:assert>

Attributes

Attribute Name Description

name required
The class name

Notes

This tag is functionally equivalent when used in either HTML or JSP.

Available Since: Version 4.2

CONFIDENTIAL 23
 JSP Tags in the pegatag Library

chart
The chart tag is used to embed an interactive chart generated by a SummaryView into a
section, a flow action, or any other HTML document (for example, a graph of work items
closed onto a dashboard).

This tag may also contain the parameter tags which could be used to pass parameters to
the SummaryView. These parameters must be defined in the Criteria section of the
Content tab of the SummaryView.

Syntax

<pega:chart name="SummaryviewName" className="ClassName"

owner=”ownerName” action=[refresh|reuse]
width="widthofthechart" height=”heightofthechart”
timeout=”integer”>

<pega:param name="[paramName]" value="[paramValue]" />

</pega:chart>

Example:

<pega:chart name="CountResolvedByResolverTop5IC"
className="$SAVE(workpool)" width="100%" height=""
timeout="3200">
<pega:param name="Division" value="HR"/>
</pega:chart>

Attributes

Attribute Name Description

name The name of the ListView being included (the “View Purpose”
key property from the ListView instance).

className optional
The class upon which the ListView is defined (the “Applies To”
class – the first key property of the ListView). If this attribute is
not included, the class of the step page is used.

owner optional
The third key property of the ListView instance. If not specified,
the default is ALL..

action optional
After the ListView report has been run once, the report data may
be put onto pages in the clipboard. If the report needs to be
displayed again, that data on the clipboard may be used, or the
report may be regenerated from the database.

CONFIDENTIAL 24
 JSP Tags in the pegatag Library

The action attribute may have one of two values, determining

which of these choices will be used:

refresh – default. Regenerates the ListView report from the

database.

reuse – reuses the report’s data (as long as it hasn’t expired)

height optional
This attribute sets the height of the chart, and may be specified
as a percentage or in pixels.

width optional
This attribute sets the width of the chart, and may be specified as
a percentage or in pixels.

timeout optional
This attribute sets the number of seconds the data may be
cached on the server. (Since charts are created from
aggregated data, as opposed to individual entries in the
database, they may be cached and redisplayed.)

Notes

The same chart should not be embedded more than once in a document.

Charts with the same name for the content page should not be embedded in the same
document.

Available Since: Version 5.2

CONFIDENTIAL 25
 JSP Tags in the pegatag Library

param
The param embedded tag is used to pass in multiple input parameters to other tags.
This tag is used by chart, listView, and reference tags.

Syntax

<pega:reference name = "property being referenced" mode = "mode-name" format =

"Rule-HTML-Property file to use/>
<pega:param name="param from HTML Property being referenced” value="value"/>
</pega:reference>

Example:

<pega:reference name=".Currency" mode="display" format="Decimal">

<pega:param name="ThousandsSeparator" value="-1"/>
<pega:param name="Precision" value="3"/>
<pega:param name="Locale" value="en_US"/>
</pega:reference>

Attributes

Attribute Name Description

name required
the name of the parameter that appears on the Parameters tab
of the Rule-HTML-Property being referenced in the tag

value the static value of the parameter.

ref the dynamic value (referenced value) of the parameter.

Notes

Either value or ref is required.

When using the param values to modify an HTML property, it is necessary to have one
pega:param reference for each parameter for which the developer wishes to set a value,
and all defined param references must be on the parameter tab of the HTML property. It
is not required to define a tag reference for each of the listed parameters on the tab, but if
a tag reference is made, it must be on the tab.

Available Since: Version 4.2, Service Pack 6.

CONFIDENTIAL 26
 JSP Tags in the pegatag Library

choose
The choose tag is used to ensure that subsequent when tags are not executed once a
former when tag has evaluated to true. It is the outer tag of a when tag section, and has
no attributes.

Syntax

<pega:choose>
<pega:when test=”A”>
HTML segment
</pega:when>
<pega:when test=”B”>
HTML segment
</pega:when>
<pega:otherwise>
HTML segment
</pega:otherwise>
</pega:choose>

In this example, if A is true, the HTML code in the B and otherwise sections will be
skipped. Conversely, if A & B are false, the body of the otherwise tag will always be
executed.

Attributes

none

Notes

It is possible - but strongly not recommended – to have other pega tags within the body of
a pega:choose tag (such as an include tag).
• If this include tag also contains a when, then the system will become confused
and errors will result.
• If the include should be executed for all of the when clauses (no matter which is
chosen within the choose clause), then the include should not be within the
choose, but OUTSIDE of it.
• If the include should be executed for only one of the when conditions, then it
should be INSIDE the when clause inside the choose.

Available Since: Version 4.2

otherwise
The otherwise tag should only be used within the body of a choose tag. The body of the
otherwise tag will only be executed if the when tags preceding it have evaluated to false.
This tag has no attributes.

NOTE: This tag is not required in the body of a choose tag, but is optional.

CONFIDENTIAL 27
 JSP Tags in the pegatag Library

when
The when tag may be used within the body of a choose tag. (Its syntax is the same as
the “standalone” when – please reference that tag for a full description.)

forEach
The forEach tag will iterate over an array of clipboard properties or pages.

Syntax

<pega:forEach name = "page or property list">

HTML segment to include
</pega:forEach>

Attributes

Attribute Name Description

name required
The array of properties or pages that will be iterated over within
the loop. This can refer to a clipboard property within either a
named page or a step page. Since it is possible to nest forEach
tags, the name can also refer to a clipboard property on the
current page within the loop ($this.property).

Notes

There are some names which begin with the “$” character (like $this or $input-mode);
these are delineated and explained in the PegaRULES online help.

Available Since: Version 4.2

getSaved
The getSaved tag retrieves the saved value from the scratch pad.

Syntax

<pega:getSaved name = "savedValueName"/>

Attributes

Attribute Name Description

name required
the name of the saved value

Available Since: Version 4.2

CONFIDENTIAL 28
 JSP Tags in the pegatag Library

include
The include tag will include a stream rule file into a JSP page. Rule-HTML-Fragment is
assumed if type is not specified.

Syntax

<pega:include name = "name of stream to include" type = "class associated with

stream"/>

Attributes

Attribute Name Description

name The name of the stream being included (static reference)

ref The name of the stream being included (dynamic reference

determined at runtime)

type The type of stream being included. It can be one of:

Rule-Obj-JSP
Rule-HTML-Fragment
Rule-Obj-Corr
Rule-Corr-Fragment
Rule-Obj-HTML
standard
noinput
fragment
property

Notes

If both the Rule including the stream and the stream itself are generated for JSP, then the
included Rule will be inlined into the rule including the file.

NOTE: either name or ref is required.

Available Since: Version 4.2

CONFIDENTIAL 29
 JSP Tags in the pegatag Library

listView
The listView tag is used to embed a ListView into a section, a flow action, or any other
HTML document (for example, to display a list of customers in a work item).

This tag may also contain the parameter tags which could be used to pass parameters to
the ListView. These parameters must be defined in the Criteria section of the Content tab
of the ListView.

Syntax

<pega:listView name="ListView name" className="aClassName" owner=""

header="[true|false]" action="[refresh|reuse]" maxRecords="integer"
removePages="[none|all|listview]“ >

<pega:param name="ViewParameter1" value="value1" />

<pega:param name="ViewParameter2" ref="value2" />

</pega:listView>

Example:

<pega:listView name="Customers" header="false"

className="MyLibrary-Customer" />

Attributes

Attribute Name Description

name The name of the ListView being included (the “View Purpose”
key property from the ListView instance).

className optional
The class upon which the ListView is defined (the “Applies To”
class – the first key property of the ListView). If this attribute is
not included, the class of the step page is used.

owner optional
The third key property of the ListView instance. If not specified,
the default is ALL..

action optional
After the ListView report has been run once, the report data may
be put onto pages in the clipboard. If the report needs to be
displayed again, that data on the clipboard may be used, or the
report may be regenerated from the database.

This attribute may have one of two values, determining which of

these choices will be used:
refresh – default. Regenerates the ListView report from the
database.
reuse – reuses the report’s data (as long as it hasn’t expired)

CONFIDENTIAL 30
 JSP Tags in the pegatag Library

header optional
This boolean attribute determines whether the ListView header
will be displayed. The default is true.

maxRecords optional
This integer attribute sets the maximum number of records that
will be displayed by the ListView report. NOTE: This value will
be ignored if paging is enabled for this ListView.

removePages optional
This attribute determines whether the clipboard pages created by
the ListView should be removed. Valid values include:

• all – default. Removes all pages created by the

Listview.
• listview – Removes the ListView definition page, but not
the results of the report page.
• none – Doesn’t remove any pages.

NOTES:
• The all and listview values are not applicable when
using a selectable ListView with the “Copy to Content
Page” option enabled.
• If pages are removed, then some actions such as
sorting and Export to Excel will result in re-running the
report (re-extracting the data from the database).

Notes

The same ListView should not be embedded more than once in a document.

ListViews with the same name for the content page should not be embedded in the same
document.

Available Since: Version 5.2

CONFIDENTIAL 31
 JSP Tags in the pegatag Library

lookup
The lookup tag is used to retrieve and display a particular string value from the database.
Use the lookup tag to either:

• retrieve and display a property value of an instance that is stored in the

database, but is not present on the clipboard. (When the instance is already on
the clipboard, use the reference tag)
• retrieve and display a localized version of a property (stored in a Rule-Obj-
FieldValue rule in the system)

Instead of using Obj-Open to open an item, the lookup uses the name of the class upon
which the specified property is defined, along with the key name values of the particular
instance of the class, in order to return a specific value of that property for that class
instance.

The first two examples of this tag specify the precise instance in the database to retrieve.
The last two examples are a specialized version of this functionality, used for localization.
The syntax is shortened, and some assumptions are made about the data.

lookup - property value

Property Value Lookup: First Variation

Syntax

<pega:lookup className=”aClass” property= ”aProperty”>

<pega:key name=”key1” value=”value”/>
<pega:key name=”key2” value=”value”/>
</pega:lookup>

Example:

<pega:lookup className=”Rule-Obj-Activity” property= ”pxHostID”>

<pega:key name=”pyClassName” value=”Data-Admin-Operator-ID”/>
<pega:key name=”pyActivityName” value=”AddOperator”/>
</pega:lookup>

Attributes

Attribute Name Description

className required
the class name of the property in the database

property required
the name of the property being referenced

CONFIDENTIAL 32
 JSP Tags in the pegatag Library

Notes

This syntax uses the pega:key information (see next section) to specify the class key
properties in order to retrieve the correct database instance.

In the example, the system would look up the activity AddOperator, defined on the class
Data-Admin-Operator-ID, to find the current value for pxHostID, and return that value.

Available Since: Version 4.2

Property Value Lookup: Second Variation

Syntax

<pega:lookup className=”aClass” property= ”aProperty”>

<pega:key name=”key1” reference=”.reference1”/>
<pega:key name=”key2” reference=”.reference2”/>
</pega:lookup>

Example:

<pega:lookup className=”Rule-Obj-Activity” property= ”pxHostID”>

<pega:key name=”pyClassName” reference =”.WorkClassInfo”/>
<pega:key name=”pyActivityName” reference =”.RuntimeActivity”/>
</pega:lookup>

Attributes

Attribute Name Description

className required
the class name of the property in the database

property required
the name of the property being referenced

Notes

This syntax also uses the pega:key information (see next section) to specify the class
key properties in order to retrieve the correct database instance.

In this example, instead of using a specific value for the pega:key, a property reference is
used, so that the value of this lookup can change depending upon runtime values.

Available Since: Version 4.2

CONFIDENTIAL 33
 JSP Tags in the pegatag Library

key
The key embedded tag is used to pass in multiple input parameters to other tags.
Currently, it is only used by the lookup tag for the property value case.

Syntax

<pega:lookup className=”aClass” property= ”aProperty”>

<pega:key name=”key1” value=”value1”/>
<pega:key name=”key2” reference=”.reference1”/>
</pega:lookup>

Attributes

Attribute Name Description

name required
the name of the key property value for the specified class

value the static value of the key property

ref the dynamic value (referenced value)

Notes

either value or reference is required.

When using either type of key values to specify a class instance, it is necessary to have
one pega:key reference for each key value which defines a class. If a class has three key
values, then all three must be specified in the lookup.

Available Since: Version 4.2

lookup - localized value of a property

All localized values for the lookup tags are stored as Rule-Obj-FieldValue instances. The
Rule-Obj-FieldValue class contains three key properties:

• Class Name (pyClassName) – the class the Field Value is defined on

• Field Name (pyFieldName) – the name of the property the Field Value is defined
on (in localization, the name of the “grouping property”)
• Field Value (pyFieldValue) – the actual key name of the Field Value

NOTE: When originally designed, the Field Value rules were used to create a drop-down
list of values to choose for a particular property. Thus, it was necessary to define the Field
Value on the same class as the property, and specify the property in the Field Name

CONFIDENTIAL 34
 JSP Tags in the pegatag Library

section, and then give the specific value for this part of the property drop-down in the Field
Value area. This functionality has been adapted for the localization process: for
localization of labels, the Field Name now refers to a “grouping property,” which groups
similar types of Field Values together (“.pyButtonLabel” “pyCaption”) and the Field Value
now points to the actual name of the Field Value rule instance.

There is also another field on the rule, .pyLocalizedValue, which is the value in the
Localized Label field which holds the translation of the Short Description.

In order for a lookup tag to find the appropriate instance in the database to retrieve, it will
require all of these properties to be identified.

There are two different ways that lookup can be enabled for localization. For each of
these, the syntax does not specify the class name of the item; this syntax signals the
2
system to always use Rule-Obj-FieldValue as the class.

Localization Lookup: First Variation

Syntax

<pega:lookup property=”.aProperty” />

Example:

<pega:lookup property=”.pyButtonLabel” />

Attributes

Attribute Name Description

property required
the class name of the property in the database

2
It is possible to use this syntax to reference a localization lookup:

<pega:lookup className=”Rule-Obj-FieldValue” property= ”pyLocalizedLabel”>

<pega:key name=”pyClassName” value=”@baseclass”/>
<pega:key name=”pyFieldName” value=”pyActionPrompt”/>
<pega:key name=”pyFieldValue” value=”Select Operator”/>
</pega:lookup>

However, it is an unnecessarily complex reference; the localization syntax described in the previous
section is strongly preferred.

CONFIDENTIAL 35
 JSP Tags in the pegatag Library

Notes

When this syntax is used to look up Field Values, there are a number of assumptions
made to complete the information needed for the lookup:

• Class name: Rule-Obj-FieldValue

• Key – “Defined on” class name: the class of the primary page present at runtime
(or its ancestors, which would include @baseclass)
• Key – Field Name: the name of the specified property (the grouping property:
“.pyButtonLabel”)
• Key – Field Value: the value of the specified property at runtime

In this example, the system will use the grouping property name “.pyButtonLabel” to look
up a value. It will look up the Rule-Obj-FieldValue instance with the following information:

• Class Name (pyClassName) – the class of the primary page (in most instances,
the system will end up finding the Field Values defined on @baseclass)
• Field Name (pyFieldName) – .pyButtonLabel
• Field Value (pyFieldValue) – the current value of .pyButtonLabel
(“RemoveFromFolder”)

The system would look at the current value of .pyButtonLabel, and then return the rule-
resolved value stored in the .pyLocalizedValue. (This could be the German, French, or
other language version of the “Remove from folder” phrase.)

Important: For this reference to work correctly, the developer must be sure that there will
be a current value of the referenced Field Value on the clipboard at execution time.

Available Since: Version 4.2

Localization Lookup: Second Variation

Syntax

<pega:lookup property=”somePage.aProperty” value=”fieldValue”/>

Example:

<pega:lookup property=”pxRequestor.pyCaption” value=”Engage Manager”/>

Attributes

Attribute Name Description

property required
the Field Name – the name of the “grouping” property of the Field
Value rule. Should always include the “pxRequestor” page.

value required
the Field Value (key name) of the Rule-Obj-FieldValue rule in the
system

CONFIDENTIAL 36
 JSP Tags in the pegatag Library

formatOutput optional
true/false value that determines whether or not the output will be
formatted using a Rule-HTML-Property Rule.

Notes

If the developer wishes to use a specific Field Value and look up its localized value, then
this alternate syntax may be used.

This syntax requires that a page be specified as part of the property reference, so the
system may determine the class name from that page. Since the “grouping property” is
generally just used to group the field values (as opposed to being an actual property), it
may not be on an actual page in the clipboard at the time it is referenced. A page needs
to be referenced which will always be on the clipboard, so the system may then search
the class hierarchy and find the Field Values in @baseclass. Since the requestor page is
always present for a work item, that page is frequently used as a “placeholder” page for
the “grouping” property.

Available Since: Version 4.2

onlyonce
The onlyonce tag allows a tag which includes some code (such as javascript) to have
that code run only once, even if it is included multiple times. (Running the same
javascript multiple times in a page causes errors.) Additional tags with the specified
name will be ignored whenever it is called, except for the first time, during the specified
interaction for one requestor.

Syntax

<pega:onlyonce name="name">

Example:

<pega:onlyonce name="StreamIncluded_DynamicSelect_Script">
<pega:include name="RequestURIInclude"/>
<script>
script here
</script>
</pega:onlyonce>

Attributes

Attribute Name Description

name required
the name given to the javascript section which is to be run only
once

Available Since: Version 5.2

CONFIDENTIAL 37
 JSP Tags in the pegatag Library

reference
The reference tag will incorporate a property value on the clipboard as output text.

If the mode is not specified, it defaults to display.

If the format is not specified, the formatting from the Rule-HTML-Property associated
with the property is used; if no HTML Property is entered in the Rule-Obj-Property form,
then the HTML Property “Default” is used.

Syntax

<pega:reference name = "property being referenced" mode = "mode-name" format =

"Rule-HTML-Property file to use"/>

Examples:

<pega:reference name="pxRequestor.pxReqServerPort" mode="normal" />

<pega:reference name=".Currency" mode="display" format="Standard"/>

<pega:reference name=".Currency" mode="display" format="Decimal">

<pega:param name="ThousandsSeparator" value="-1"/>
<pega:param name="Precision" value="3"/>
<pega:param name="Locale" value="en_US"/>
</pega:reference>

Attributes

Attribute Name Description

name required
the name of the string being included, where the string can either
be a reference to a clipboard property or a dynamic reference to a
variable name in the current stream($page-xxx, $stream-xxx) or
for each loop ($this)

format specifies the Rule-HTML-Property stream to use to format the

output. If there is a property referenced in name, the stream
specified in format overrides the Rule-HTML-Property that is
associated with that property. NOTE: If a format is specified, then
the mode can only be either display or input.

mode specifies how the output should be displayed. (See Notes for a
full list of Mode descriptions.)

This tag is also available in an abbreviated format, which is functionally equivalent to the
full format (above).

<p:r n="name of the value being referenced" m="text" f="Rule-HTML-Property file to

use"/>

CONFIDENTIAL 38
 JSP Tags in the pegatag Library

-- n: the name of the string

-- f: the format
-- m: the mode

Notes

The syntax of the third example uses the pega:param information (see next section) to
specify the format parameters in order to retrieve the correct database instance. In this
example, the system would place the names and values for the parameters
ThousandsSeparator, Precision, and Locale on a new Parameter page, to be used when
the Rule-HTML-Property Decimal is run to format the Rule-Obj-Property .Currency.

Available Since: Version 4.2

Mode Notes

Possible options for mode include:

Option Description

block Use this option for processing the property to display HTML tags
without interpreting them.
If the source text contains a newline character, the system
replaces it with <BR/> tag. It also performs the conversions listed
for the NORMAL keyword, so that the actual value of the property
is displayed, even if it includes characters that otherwise could be
interpreted as HTML commands.

display This keyword instructs the system to use an HTML Property rule
with $mode-display. Stream processing adds a single space
before the value and a single space after the value.
input Add INPUT to present a property in update mode so that a user
can enter, or select, a value for the property. For example:
{.myText INPUT}
If the HTML Property rule referenced in the myText property
definition instructs the system to display the property as a text
box in update mode, it displays myText as a text box.

literal If the value of a property is an HTML text fragment, and is to be

processed as HTML, add the LITERAL option to the Reference
directive. For example:
{.myText LITERAL}

normal Use this option to convert the <,>, & and * characters to the
corresponding HTML entities (&lt; &gt;, &amp; and &ast;
respectively) so that they appear correctly in the resulting display
or output.

text Use this option for text areas. Add the TEXT option to a
Reference directive if the property defines a text area, and you
want the <BR> tag to be converted to a new line character.

CONFIDENTIAL 39
 JSP Tags in the pegatag Library

stream Use this option to instruct the system to replace line breaks with
<BR> followed by one space character. This can be useful in
situations when the line length is not appropriate.

Add the STREAM option to a Reference directive to instruct the

system to process the property to display HTML tags without
interpreting them.

In addition, the system replaces each newline character and

<BR> with a space. It also performs the conversions listed for the
NORMAL keyword, so that the actual value of the property is
displayed, even if it includes characters that otherwise could be
interpreted as HTML commands.

Examples:

Mode affects how the underlying Rule-HTML-Property renders the property value. For
example, the tag:

<pega:reference name=".pxCreateDateTime" mode="display"/>

might render:

Nov 16, 2004 03:00:00 AM EST

For the raw Pega time value, the “literal” mode could be applied:

<pega:reference name=".pxCreateDateTime" mode="literal"/>

would render:

20041116T080000.000 GMT

In addition, this tag supports the following symbolic values:

• $index
• $none
• $page-allmessages
• $page-all-messages
• $page-class
• $page-definition
• $page-message
• $page-name
• $save
• $stream-definition
• $stream-handle
• $this
• $this-definition
• $this-message
• $this-name
• $this-qualifier
• $this-value

For full details on using these symbolic values, please reference the on-line help.

CONFIDENTIAL 40
 JSP Tags in the pegatag Library

save
The save tag copies a name and value pair to temporary scratchpad during HTML
execution. The value can be retrieved later with the <pega:getSaved…/> tag.

Syntax

<pega:save name = "name for value" value = “the value” />

Example:

<pega:save name = "tempBuildInfo" value = “BuildNumber” />

Attributes

Attribute Name Description

name required
the name of the saved value

value the value (static value)

ref the dynamic value (referenced value) determined at runtime

append appends information onto the value

appendref appends information onto the value in a reference

prepend attaches information to the front of a value

prependref attaches information to the front of the value in a reference

Notes

Either value or ref is required.

The append and prepend functionality works for the string or label that is returned by the
function. In the example above, the name of this temporary item is “tempBuildInfo.” This
object has the value “BuildNumber.” If department information was prepended to this, the
syntax would be:

<pega:save name = "tempBuildInfo" value = “BuildNumber” />

<pega:save name = "tempBuildInfo" prepend = “Engineering” />

string return value: EngineeringBuildNumber

<pega:save name = "tempBuildInfo" ref = “.BuildNumber” />

<pega:save name = "tempBuildInfo" prependref = “Eng-” />

string return values: Eng-1201

Eng-1202
Eng-1203 etc.

Available Since: Version 4.2

CONFIDENTIAL 41
 JSP Tags in the pegatag Library

url
The url tag provides a means to encode a URL string with Pega-specific keywords and
information which refer back to the server on which the PegaRULES system is running.
This tag accepts Pega-specific encoding options as input parameters. These options are
not required, but one or more of them can be passed in as values, using the option tag.

Syntax

<pega:url value="pyStream=MyStream"/>

Attributes

Attribute Name Description

value required
the string that should be appended to the URL.

Available Since: Version 4.2

option
This tag is used to pass multiple input options into a tag. Currently, it is only used by the
URL tag.

The list of options that can be passed into the URL tag include:
transid or t (append the current transaction id onto the end of the url)
frame or f (append the current frame name onto the end of the url)
primary or p (append the name of the current primary page onto the end of the url)
long or l (append all of the above)

Syntax

<pega:url value="pyStream=MyStream">
<pega:option name="transid"/>
<pega:option name="frame"/>
</pega:url>

Available Since: Version 4.2

CONFIDENTIAL 42
 JSP Tags in the pegatag Library

when
The when tag is used to control page flow. The body of the when tag will only be entered
if the boolean statement in the name, test, or java attribute evaluates to true. The test
attribute can be a when rule, a mode (to test current input mode), a boolean java method
for a clipboard property or all of these combined. The Java attribute should be used to
execute Java script.

Syntax

<pega:when test="$mode-display">
HTML segment
</pega:when>

<pega:when test="$this:isBad">
HTML segment
</pega:when>

<pega:when test="canProcess && $mode-display">

HTML segment
</pega:when>

<pega:when java="<%=
tools.getProperty("pxObjClass").getStringValue().equalsIgnoreCase("Rule-Obj-JSP")
%>">
</pega:when>

<pega:when name=”canProcess”>
HTML segment
</pega:when>

Attributes

Attribute Description
Name

test statement being tested where test can reference a property method such as
isBad ($this:isBad), any of the reserved keywords for mode ($mode-display,
$mode-input, $input-enabled). Please refer to Known Issue #3 (Complex
&& and || logic) for full details on the syntax of this attribute.

java Allows users to write a Java statement whose outcome will be a boolean
variable. The java statement must be enclosed by <%= %> .

name Name of Rule-Obj-When rule to evaluate

CONFIDENTIAL 43
 JSP Tags in the pegatag Library

Notes

NOTE: One of the attributes (test, java, or name) is required, and only one may be
specified.
When forming these expressions, it is possible to specify && (“logical and”), || (“logical or”)
and a mixture of &&, || and ! statements, as well as the standard “greater than” or “less
than.”

The following operators are permitted:

== (or =)
!= or !( x == x )
>
<
>=
<=

The following expressions are acceptable:

A == A
A=A
A != B
A<B
!(A == B)
!(A >= B)
A == A || B > C
A < B && E > D
!(A > B) && E > D
A && B
A || B
!A && B
!(A && B)
!(A || C)
(A == "test") || B

Where A, B, and C can be:

• a named when block

• a “symbolic keyword” such as $mode-input
• a Java clipboard property method such as $this:isModifiable
• a property = or != to something such as .pxObjClass == "Rule-Obj-Activity"

Complex && and || statements are not supported, such as statements with parentheses
which change the natural computation order of the binary operators (force the ordering of
the expression):

<pega:when test=”((canProcess && $input-enabled) || $this:isScalar) &&

isAdministrator”>
</pega:when>

It is not possible to mix Pega tokens (such as $this, $mode-input, etc.) with Java
expressions. In order to include both in a script, replace the entire statement with Java
script, where any valid Java boolean expression may be used.

CONFIDENTIAL 44
 JSP Tags in the pegatag Library

<%= tools.getActive() != null &&

tools.getActive().getString("pxObjClass") == "Rule-Obj-Activity"
%>.

Available Since: Version 4.2

withEmbedded
Used to replace the embedded page with a different page.

Syntax

<pega:withEmbedded name = "name of page being embedded">

HTML segment
</pega:withEmbedded>

Attributes

Attribute Name Description

name required
specifies the name of the page

Notes

For all the with tags listed, the original page property value is restored after the tag body
(designated in the examples as HTML segment) is executed.

Available Since: Version 4.2

CONFIDENTIAL 45
 JSP Tags in the pegatag Library

withPage
Used to replace the primary page with a different page (PAGE option).

Syntax

<pega:withPage name = "name of page">

HTML segment
</pega:withPage>

Attributes

Attribute Name Description

name required
specifies the name of the page

Notes

For all the with tags listed, the original page property value is restored after the tag body
(designated in the examples as HTML segment) is executed.

Available Since: Version 4.2

withReference
Used to define the active property reference.

Syntax

<pega:withReference name = "name of property">

HTML segment
</pega:withReference>

Attributes

Attribute Name Description

name required
specifies the name of the property

Notes

For all the with tags listed, the original page property value is restored after the tag body
(designated in the examples as HTML segment) is executed.

Available Since: Version 4.2

CONFIDENTIAL 46
 JSP Tags in the pegatag Library

withTarget
Used to designate a property as a target property for HTML-defined <select> and <input>
tags.

Syntax

<pega:withTarget name = "name of property">

HTML segment
</pega:withTarget>

Attributes

Attribute Name Description

name required
name of the property

Notes

This functionality is not yet used, but is included for future functionality.

CONFIDENTIAL 47
 JSP Tags in the pegatag Library

Appendix: Directive Comparison - HTML

Syntax vs. new JSP Syntax
Directive Tag name Embedded
(HTML) (JSP) tag
Assert assert
like an choose
ElseWhen
choose otherwise
choose when
Comment
Delimiters
Foreach forEach
getSaved
Include include
Java
Java
Reference
Literal
Lookup lookup
lookup key
Reference reference
Save save
URL url
url option
When when
With
withEmbedded
withPage
withReference
withTarget

CONFIDENTIAL 48