User interface - Concepts and terms

Based on HTML and XML standards, Process Commander can support a wide range of user interaction facilities and
approaches. Your application's user interface can take into account the environment, the domain knowledge of your users,
their skills, locale, and language.
The appearance, branding, and interaction dynamics of your user interface can match the context and language that is
natural to your application's users.
Evolving an application's user interface is best done by designers and developers who have both application domain
knowledge and usability skills.

Producing HTML displays and forms

Process Commander includes standard facilities for those workers and managers who use Process Commander-based
applications throughout the workday. These facilities support:

Entry of new work items and covers

System-maintained worklists of assignments sorted by decreasing urgency

Finding, reviewing, updating, and performing assignments

Sophisticated and powerful standard forms known as harnesses are designed for reuse and customization.

Defining user input forms and displays

For access through the standard portal, Process Commander uses harness rules (Rule-HTML-Harness rule type) for work
items. Six other rules support the presentation of work items:

Section rules define the contents, appearance, and behavior of portions of harness forms.

Fragments contain reusable HTML text elements not dependent on a class/

Control rules determine the appearance of a single property on an HTML input form or display.

Text File rules, which can define static aspects of your user interface such as Cascading Style Sheets or
JavaScripts.
Binary File rules, which identify images such as JPG or GIF files.
The HTML text you enter into HTML rules is known as source HTML. It contains ordinary HTML code plus JSP
tags or directives server-side instructions that Process Commander evaluates at runtime to compose the final HTML it
sends to the HTTP server (and ultimately to a user's browser session). Known as stream processing, this evaluation
accesses the clipboard for text values to insert into the output HTML, incorporate the text of other HTML rules, provide
conditional if-then-else testing, and looping through arrays.

Harness forms use the pega:include JSP tag to incorporate multiple sections, which in turn use standard styles and
fragments to present properties, labels, and images. For your application, you can copy and tailor parts of these forms as
necessary, while inheriting the standard parts.

Tools
These tools support your evolution of the user interface of your applications:

Harness rules preview and the Application Explorer Allow you to interactively revise the content and the layout
of a user form or flow action form

UI Gallery Presents working examples of controls and user interface features

Branding wizard Defines and maintains a family of styles for the User portal, user forms, and reports

Rules Inspector tool Identifies the harness, section, HTML rules and properties that together make up a form

Image Library gadget Helps you find and identify the name of images that are available as binary file references

Style Discovery tool and Style Viewer Allow you to learn about and experiment with styles

Clipboard tool Shows the current property values in internal format

Harness form - Completing the Layout tab

Use the controls at the top of this tab and drag and drop operations to review or update this harness rule and associated
section rules.

Basics

The tab presents a real-time preview of the user form, allowing you to adjust the contents, position, style, and other aspects
of the elements in the form quickly.

Areas of the layout that correspond to section rules (or other elements) that you cannot update appear with a gray
background. This may mean that the rule needs to be checked out by you, or belongs to a locked RuleSet version, or
belongs to a RuleSet version that you are not allowed to update.

You cannot use this tab to modify section rules (referenced in the harness rule) with the Auto-generated
HTML? checkbox cleared (on the HTML tab). These are marked Manual
this tab to modify section rules are in the legacy format. These are marked

HTML on this tab. Similarly, you cannot use

Not Upgraded on this tab.

When you save this rule form, Process Commander also saves any other section rules you have open that this rule
references, and validates the rules as they are saved.

At runtime, the initial state of each collapsible element on a user form collapsed (

) or expanded (

) is

determined by the state on the Harness form when you save the form.

As a best practice, build your application skin (using the Branding wizard) before you develop harness rules, especially if
you are using SmartLayouts (with spacing determined by the skin styles.) The system renders the Layout tab using the
styles of the skin rule identified in the Skins field of theRun Process In group of your General preferences. If the Skins field
is blank, these displays use the styles marked Work on the Styles tab of the skin identified in your current portal rule.
See Designer Studio Setting your preferences.

Using the Harness form to review or update a harness rule creates a clipboard page and initializes properties. This may
in turn cause declarative processing to execute. Use caution before implementing any OnChange declarative processing
that produces database updates.

Identifying controls on this tab

Controls that alter the preview

The preview area of this tab holds an approximate visual presentation of the runtime appearance of the flow action. These
buttons do not affect the contents of the rule, only the display on this tab:

Click the

button to present the SmartFrames wireframe preview. Blue wireframe rectangles help you

understand the structure of the section, names of rules referenced in this rule, and the size and other relationships of
elements in the section.

Click the

button to hide wireframes, providing a less busy and more faithful preview.

Controls that alter a layout table (grid)

These controls operate on a table structure. Select one or more cells first, and then click the control to apply the operation
described. When a control is not available (grayed), it cannot be applied to the current selection.

Control

Description
Delete the contents of a single cell (not a row or column).
Insert a new row before (above) the selected row.
Insert a new row after (below) the selected row.
Delete the selected row.
Insert a new column before (to the left of) the selected column.
Insert a new column after (to the right of) the selected column.
Delete the selected column.
Merge right Combine the selected cell and the cell to the right.
Merge down Combine the selected cell and the cell below it.
Unmerge Undo the previous merge.

You can also alter the table structure with Windows pointer operations. Select a row, cell, or column and right-click to access
a context menu. Select menu operations Cut, Copy, Paste, Insert Row,Delete Row, or Delete Column.

Tabs and +/- controls

Sections in a harness may be presented as horizontal elements (

) or as clickable tabs (

). These are "live" in

the Layout tab; click a tab to bring it to the front, or click a plus sign to expand a section.

When you save a Harness rule form, the state of these controls is saved as well, and determines the initial presentation of
the form. To achieve the desired results, before you save the Harness rule form:

Click one tab to make it front-most when the user form initially appears at runtime, or

Click the

or

as desired to control the initial presentation of a section or other element

Structure of a harness-based form

Structurally, every harness consists of one or more containers. (The container structure is not required for those harness
rules that are defined through handcrafted HTML code.) A container can provide a visual grouping of multiple sections.

Headers belong to containers. A container may have a horizontal header, a set of tabs identifying the (top-level) sections it
contains, or no header.

Each container can contain one or more sections, which in turn can contain layouts, repeating layouts, and other sections.
Sections contain cells, arranged in rows and columns.

Prototyping a harness before the work item properties are defined

You can rapidly mock up the layout, labels, and controls on this tab before all properties it ultimately will reference are
defined. The development effort you make in designing layout is not wasted, as the resulting Harness rule is a valid starting
point for further evolution after the property rules are created.

When you first drop a control dragged from the Basic Group, the control initially references a standard placeholder property,
for example @baseclass.pyTemplateInputBox. You can save and preview the Harness form (although these properties are
not part of your application's work items).

To produce a harness rule with the appropriate layout, drag and drop the controls, adjust the labels, but do not complete the
Cell Properties panel. Reopen the Harness form and update each Cell Properties panel later, when the real properties are
defined.

For an example of this approach, see Pega Developer Network article

PRKB-25216 Use pyTemplate properties and

controls to rapidly prototype user forms.

Working with the Cell Properties panel

Each control is defined by your inputs in floating panel, which you can pin for faster input. To open the panel, select the
control (after dropping it) and click the magnifying glass (

) icon that appears. Use these controls on the header of floating

panel:

Pin the panel to a location. The OK button disappears, and each input you enter is immediately applied to
the open rule form.
Release the pin. The OK button appears. Your inputs do not affect the open form until you click OK .

Collapse (hide) the panel body.

Expand a collapsed panel body.

Close the panel. If you have entered changes that are not yet applied, a warning dialog may appear,
depending on the Warn on modified checkbox in the SmartFrames Edit area of the Editpreferences group.
See Designer Studio Setting your preferences.

Layout Group:

Click the down arrow (

Contr
ol

Adding a container, section, layout, tab, or repeating layout

) in the Container control group (

) and select a control:

Description

Add a panel set to this harness, to support a composite portal. See Adding a panel
set.

Add a container to the harness form. Every harness must contain at least one
container. The sections within a container may be presented vertically or with tabs.
See Adding a container.

Add a tab to a harness. See Adding a tab.

Add an accordion to the harness. See Adding an accordion.

Add a section rule into this harness. See Adding a section.

Add a layout to the harness a <TABLE> element containing one or more rows

and one or more columns. You can then change the number and size of rows and
columns, and set up the contents of each cell (a <TD> HTML element). See:

Adding a layout

Adding a Row Repeat layout

Adding a Column Repeat layout

Adding a Tabbed Repeat layout

Adding a Grid layout

Adding a Tree Grid layout

Adding a Tree layout

Basic Group:

Placing a property or label in a cell

A cell can hold a label or property value or a form field that accepts a user-entered property value. The property value uses a
control rule to present the value in read-only or read-write mode.

Click the down arrow (

Contr
ol

) in the Basic control group (

) and select a control:

Description

Add a static read-only text label into a cell. Adding a label.

Add a Text Input, which corresponds to .pxTextInput control rule. Adding a
Text Input control.
Add a TextArea, which can contain more than one line of text.
Corresponds to the.pxTextArea control rule. Adding a Text Area control.
Add an icon to the form, in a cell or on a header. When clicked at
runtime, the icon starts an action. Corresponds to the .pxIcon control
rule. Adding an icon

Place a button into a cell at the bottom of the form. When clicked at
runtime, the button starts an action. Corresponds to a .pxButton control
rule. Adding a button.
Add a checkbox representing a TrueFalse value. Corresponds to
a.pxCheckbox control rule. Adding a Checkbox.
Add a radio button group representing a property value. Adding a radio
button group.
Place a text link in a cell. When clicked at runtime, the link starts an
action. Corresponds to a .pxLink control rule. Adding a Link control.

Add a text box containing a Date or DateTime value. Corresponds to

a.pxDateTime control rule. Adding a Calendar control.

Add a Select control that presents a fixed list of values. Adding a Select control.

Include an image in the form. Adding an Image.

Advanced Group

Click the down arrow (

Contr
ol

) in the Advanced control group (

) and select a control:

Description

Reference, in a cell, a paragraph rule that presents only read-only text

and images using rich text. Optionally, you can link a SmartInfo pop-up
section with the paragraph. Adding a paragraph.

Use an AutoComplete text box to present a drop-down list of dynamic

choices computed by an activity. Adding an AutoComplete field.
Add a red label that opens a pop-up SmartInfo section when the user
hovers the mouse pointer over the label. Adding a Smart Label.
Add a dynamic drop-down list. Adding a Dynamic Select control.
Adding a control that allows multiple selections from a possibly long
list. Adding a list-to-list control.
Presenting rows of a report, optionally allowing selection. Adding a List
View display.
A cell can contain an interactive chart, defined by a summary view rule
with a completed Chart tab. Adding a chart.
For harnesses that are part of a composite application built with Internet
Application Composer only. Add a hidden field to expose a property
value, making it available to the external page that displays the
composite application. See Adding a Data Field control.
Add a menu to a composite portal. See Adding a Menu Bar.

Adding a Work Area to a composite portal. Adding a Work Area.

N/A

In addition to these Advanced controls, you can add interactive data

displays to support quick review or editing for a Page List or Value
List. Adding a Tree,Adding a Grid, Adding a Tree Grid.

Dragging a property from the Application Explorer

You can complete two cells of a layout in one step if the left cell is to contain a text label and the right cell is to contain a field
corresponding to a property on the Application Explorer.

1.

Locate and expand the work type that contains the property on the Application Explorer.

2.

Expand the Data Model category (

3.

Select the blue dot (

desired cell.

4.

The system places the Short Description text of the property as a label in the left cell. It places the property as a
(read-write) field in the right cell. You can adjust the settings for these cells.

) and the Property rule type to list property names.

) for the Single Value property to be placed in the field. Drag and drop the dot into the

5.Standard Harness rules

6.

Several standard rules are available for your use in the @baseclass, Work- class, or othr classes. Other standard
harness rules not listed are used in the Application Accelerator and other wizards. Your custom harness rules
typically override these by using the same Purpose key part.

7. A to G

Harness

Description

More

@baseclass.
ActivityStatusSucces
s

Presents a form when a top-level activity

completes with presenting an HTML
display. ("The operation completed
successfully, but returned no content."
with green checkmark.)

How to
customize the
activity success
and exception
windows

@baseclass.
ActivityStatus
ExceptionHandler

Presents a form when an activity fails or

an uncaught Java exception occurs.
("Please contact your System
Administrator ." with red X.)

How to
customize the
activity success
and exception
windows

AutoClose

Closes the work object form automatically;

an alternative to Confirm when there is no
new information to display.

Confirm

Presents a read-only confirmation display

of the work item, acknowledging user
completion of an assignment. Contains
the Get Most Urgent button. This button is
by default linked to the standard
activityWork-.GetNextWork. Your application
can override that activity.

Maximizing
User
Productivity
with
GetNextWork

DisplayInput

Special purpose, not for use in BPM

applications that use flows. Supports
testing of business rules decision
applications created by the Application
Accelerator.

business rules
engine

DisplayOutput

Special purpose, not for use in BPM

applications that use flows. Supports
testing of business rules decision
applications created by the Application
Accelerator.

business rules
engine

8. H to P

Purpose

Description

More

LockInfo

For diagnostic or debugging purposes,

displays the requestor session holding a lock
on the work object.

Understanding
object locking

Work-.New

Supports entry of a new work item and the

start of a flow rule execution for that work
item.

Working with user

forms (V5.X)
Working with user
forms (V6.2)

NewCovered

Allows a user to create both a cover work

item and in the same form create one or
more covered work items.

cover

NewSample

For work item creation, used by the (basic)

Application Accelerator. Incorporates styles
from the standard Userskim rule, introduced
in Version 5.3.

About the
Application
Accelerator

Work-.Perform

Allows a user to select a flow action from a

drop-down list in the Take Action section,
and complete an assignment based on the
selection.

perform
Working with
user forms
(V5.X)
Working with
user forms
(V6.2)

Perform_Buttons

Allows a user to select a flow action by

clicking a button, rather than choosing from
a selection list.

Used primarily
in V5
applications.

Perform_Step

Allows a user to complete the flow action

marked as most likely immediately, rather
than choosing this action from a selection
list.

Used primarily
in V5
applications.

PerformExternal

Supports directed Web access.

directed Web
access

PerformSample

Simple harness with Take Action area,

copied into applications created by the basic
Application Accelerator.

About the
Application
Accelerator

PerformScreenFlo
w

Supports execution of screen flow rules with

breadcrumbs.

screen flow

PortletHarness

A template rule for building application

harness rules, configured to generate

portlet

portlet-compliant HTML.
PrintOptions

Allows a user to select which top-level

sections are to be printed.

PrintView

Provides a presentation of a work object

suitable for printing.

pyCMConfirm

Reserved. Do not use.

pyCMPerform

Reserved. Do not use.

pyCMReview

Reserved. Do not use.

9. R to Z

Purpose

Description

More

Reopen

Allows a user to reopen a resolved work item.

reopen

Review

Presents the work item and assignment in readonly mode, not allowing data entry.

ReviewSample

Presents the work item and assignment in readonly mode, not allowing data entry. Copied into
applications created by the basic Application
Accelerator, with the name Review.

RuleForm

Second key part of multiple standard harness

rules that define the structure of rule forms.
Reserved.

SimpleConfirm

Similar to the Confirm harness rule, but with

portlet-compliant HTML. Use this version when

About the
Application
Accelerator

portlet

your flow application is a JSR 168 portlet that

will be displayed by a portal server.
SimplePerform

Similar to the Perform harness rule, but with

portlet-compliant HTML. Use this version of
the Perform harness when your flow application
is a JSR 168 portlet that will be displayed by a
portal server.

portlet

TabbedScreenFlo
w

Supports execution of screen flow rules with a

tabbed layout. If the primary screen flow calls a
subflow screen flow, a second level of nested
tabs appears.

screen flow

TreeNavigation

Alternative for screen flow rules, where a left

tree structure presents flow navigation details.

screen flow

Section rules
Purpose
Use section rules in conjunction with harness rules to define the appearance of user forms, rule forms, or composite portals.
A section rule defines the appearance and contents of one horizontal portion of a form. Harness rules define complete forms
that support all user interactions that create, update, and resolve work items.
Process Commander contains dozens of standard harness and section rules. You can copy and tailor these standard forms
to meet your application needs.

Controls
Layout

Column
Repeat
Tabbed
Repeat

Basic

Row
Repeat
Tree

Tree Grid

Grid

Advance
d

Where referenced
Rules of the following types can reference a section rule:

Harness rules

Other section rules

List view and summary view rules, as the contents of a pop-up SmartInfo window.

Paragraph rules, as the contents of a pop-up SmartInfo window.

Access
Use Application Explorer to access section rules that apply to the work types in your application. Use the Rules by Type
Explorer to list all the section rules available to you.

Development
For section rules that use the SmartFrames format, you can maintain the section rule directly from the Harness rule form (as
well as from the Section rule form).

Category
Section rules are instances of the Rule-HTML-Section class. They are part of the User Interface category.

Standard Section rules

Your system contains hundreds of standard section rules. Most useful in your application are those that apply to
the Work- or Work-Cover- class. Others typically that apply to @baseclass support a composite portals. (Additional
standard sections support developer-oriented flow processing, such as that provided by the Application Accelerator and
Connector wizard.)

To understand the structure of a harness-based form, use the Rules Inspector tool to identify the underlying harness,
section, and property rules.

To see a complete list of the standard and custom section rules available to you (based on your RuleSets and security), use
the Rules by Type Explorer.

These standard section rules are notable:

Sections for User forms (A to H)

Name

Purpose

Work-.Action

For V5 only. Presents, as a drop-down list, the available flow

actions available to a user who is performing an assignment.
Referenced in the standard harness rule Work-.Perform.
For new V6 applications, use or copy the standard action
sectionWork-.pyActionArea. See Presenting flow actions.
Work-.pyActionArea

Recommended action section for new applications. See Presenting

flow actions.
Work-.Action_Buttons

For V5. Presents an array of buttons identifying the flow actions

available to a user who is performing an assignment. Referenced in
the standard harness rule Work-.Perform_Buttons.

For new V6 applications, use or copy the standard action

sectionWork-.pyActionArea. See Presenting flow actions.
Work-.ActionExternal

Supports external assignments.

Work-.Action_Step

For V5. Presents the preselected flow action as a default choice,

with others available through buttons. Referenced in the standard
harness rule Work-.Perform_Step.
For new V6 applications, use or copy the standard action
sectionWork-.pyActionArea. See Presenting flow actions.
Work-.ActionScreenFlo
w

Presents actions to a user during execution of a screen

flow.

Work-.AllMessages

Uses the $ALL-MESSAGES keyword to cause display of all

messages associated with the current base page.

Work-.AutoClose

When expanded, causes the work item form to close.

Work-.BodySample

Copied into applications created by the (basic) Application

Accelerator. Introduced in Release 5.3. About the
Application Accelerator.

Work-.CoreParty

Captures information about the work parties involved in

the work item; allows the user to add a party (subject the
relevant work party rule).

Work-.CoreSummary

Contains the pyDescription and pyProblemReason properties.

Work-.Details

Aggregates four other standard

sections: EffortandCharges,Responsiveness, Ownership,
and Resolution.

Work-.Flows

Supports the Start New Process button, that allows users to

select and start a second (or additional) flow execution on
the current work item. Appears in
most Perform and Update harness rules. Lists only flow
rules that belong to the user's RuleSet list and that have
the Can be added to a work item? box on
the Process tab selected.

Work-.HeaderSample

Copied into applications created by the (basic) Application

Accelerator. Introduced in Release 5.3. About the
Application Accelerator.

Sections for User forms (I to Q)

Name

Purpose

Work-.NewHeaderSample

Copied into applications created by the (basic)

Application Accelerator. Introduced in Release 5.3.

Work-.Ownership

Displays the pyOrigUserID, pyContactChange,

andpxCreateDateTime properties.

Work-.PartySimple

Captures information about the work parties involved in

the work item; allows the user to add a party (subject
the relevant work party rule). Copied into applications
created by the (basic) Application Accelerator.
Introduced in Release 5.3.

Work-.PortletSection

Template rule, copy for sections that are to support

access through JSR-168 portlets.

Work-.ProcessSteps

Supports horizontal presentation of the breadcrumbs

control.

Work-.ProcessStepsVertic

Supports vertical stack presentation of the breadcrumbs

control.

al
Work-.ProcessSteps
_ScreenFlow

Supports horizontal presentation of the breadcrumbs

control inside the action frame.

Sections for User forms(I to Q)

Name

Purpose

Work-.Responsiveness

Displays properties that convey customer

satisfaction, elapsed time in various statuses, and
acknowledgment details.

Work-.Resolution

Supports users' ability to reopen a resolved work

item.

@baseclass.SmartInfoClickabl
e

When included within a pop-up section that is to be

presented as a SmartInfo or SmartLabel pop-up,
adds a close box to the pop-up. The SmartInfo popup window remains open until the user clicks the
close box or another button on the form.

Work-.WordInclude

Supports inline editing or display of property values

using Microsoft Word. See How to implement inline
Word editing.

Work-.WorkItemSmartInfo

Supports the hover-and-see worklist feature.

See How to implement "hover-and-see" worklists
with SmartInfo.

Sections for Composite Portals

These section rules provide capabilities similar to "gadgets" in legacy User portals. See How to build a composite portal.

Name

Purpose

@baseclass.Dashboard

Presents four interactive charts summarizing work

processing, as in the Manager portal.

@baseclass.FindWork

Supports searching for work items.

@baseclass.LogOff

Provides a Log Off button or link.

@baseclass.NewWork

Allows users to enter a new work item. Various formats.

@baseclass.Profile

Displays selected facts about the operator profile, and

includes a button that provides a full profile display.

@baseclass.pxCalendar

Displays a month grid with individual events on each day.

See Using and configuring the pxCalendar section.

@baseclass.RecentWor
k

Displays recently opened work items.

@baseclass.RecentWor
k

Displays a worklist.

Other sections

Name

Purpose

@baseclass.pyGridModalTemplat
e

Template section rule to copy for modal

dialogs accessed from the Grid layout.

@baseclass.pyModalTemplate

Template section rule to copy for modal

dialogs for local flow actions.

Suggested Approach
Follow these steps to add a SmartLabel control to a harness, section, or flow action form.

1. Identify or create the section rule. In most cases, set the Applies To key part of the section rule to match the Applies To
key part of the rule that is to contain the SmartLabel.

2. Open the harness, section, or flow action rule. Select SmartLabel from the
Advanced group of controls.

3. Drag the control from the menu and drop the control in a cell. Click the magnifying
glass icon to the right of the cell to open the Cell Properties panel.
4. Complete the Cell Properties panels. On the Field tab, accept the default placeholder property.pyTemplateSmartLabel.
On the Presentation tab, click the magnifying glass icon at the right of the Format field.

5. Complete the pop-up Params window to supply three parameters for the SmartLabel: the text of the label, the second key
part of the section, and header text for the pop-up window.

6. Click Save to close the

Params window.
7. Optionally, complete additional fields on the Presentation and Conditions tabs of the Cell properties panel to
control additional aspects of the label.
8. Click Apply to apply changes to the Cell Properties panel. Click OK to close the Cell Properties panel.

9. Save the rule form. Test with the Preview toolbar button, the Run toolbar button, or in context of the application.

How to use regular expressions to validate user

input
Summary
Regular expressions provide a popular means to search text for a pattern. You can use regular expressions in edit validate
rules (Rule-Edit-Validate rule type) in your application to check the format of a user input.

Because regular expressions can describe a wide variety of text patterns, this approach can provide improved data
validation without requiring your development team to write and test long Java routines.

Suggested Approach
An edit validate rule (Rule-Edit-Validate rule type) checks the format of a text value, such as a value typed into a form by an
application user. The result outcome is either true the value does meet the criteria defined in the rule, or false the input
value is rejected with a message.

In general, Process Commander developers need Java skills to create new edit validate rules. However, Java includes the
well-known pattern matching facility known as regular expressions. This facility, like the UNIX grep command, tests an
input string against a pattern, finding the first match (if any), or all matches. Using a short Java snippet, an edit validate rule
can test an input string against a regular expression.

Many books, Web sites, and software products explain regular expressions, which are not explained here. (For the
complete, official specification see

http://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html. The simple

example below illustrates a Canadian postal code check, but other more complex regular expressions can be tested with
similar code.

Example: Canadian Postal Codes

Every postal code for Canada consists of seven characters (including a single space) in the format ANA NAN, where A is a
letter and N is a digit from 0-9. The first character is one of 18 specific letters; others are not so constrained. For example,
the Pegasystems office in Toronto is located in Postal Code M5X 1E3.

1. Develop and test the regular expression.

The regular expression [ABCEGHJKLMNPRSTVXY][0-9][A-Z]

[0-9][A-Z][0-9] captures the

Canadian Postal Code format. To confirm this:

1.

Open the built-in regular expression tester activity Code-Pega-Parse.RegExpTester. This supports the same Sun
Microsystems implementation that the edit validate rule executes.

2.

Click the Run toolbar button (

3.

Click

4.

Complete the Regular Expression field. Enter a test string in the Source field.

5.

Click Test Expression.

).

Run Rule and then click Execute. (Leave the parameters blank)

This test case confirms that the source "M5R 2E8" matches the regular expression pattern.

A second test case confirms that D5R 2E8 does not match. D is not one of the allowed first letters.

Note that the tester may find a match as a substring of a longer string:

2. Create the Edit Validate rule

Save the pattern you tested. in a scratch text file. Create an edit validate rule that uses
thejava.util.regex.Pattern class to apply the pattern to the predefined input variable

theValue:

Paste the pattern you tested into the compile( ) method. In this example, the entire Java Source field contains only a few
lines of code:

boolean retval = false;

if (theValue.length() == 7 ) {
java.util.regex.Pattern p =
java.util.regex.Pattern.compile("[ABCEGHJKLMNPRSTVXY][0-9][A-Z] [0-9][A-Z]
[0-9]");
java.util.regex.Matcher m= p.matcher(theValue);
retval = m.matches();
}
return retval;

3. Reference the edit validate rule in an activity or validate rule.

Edit validate rules execute through activities or through validate rules (Rule-Obj-Validate). To illustrate one use of the
Canadian Postal Code, you can override the standard validate rule Data-Party.WorkAddress, which by default requires only
that the property pyWorkPostalCode not be blank.

Enter "Canadian Postal Code" in the Validate field and an error message (or Rule-Message key) in theError Message field.

(For testing purposes, delete the row for the pyStateCode property.)

4. Test
To exercise the validation rule and edit validation rule:
1.

Select the File > Open > Work Pool > Sample Work menu item to access the PegaSample sample application.

2.

Select the Run > Process > General Task menu item to enter a General Task

3.

In the Parties section of the New form, select Add Party... Customer.

4.

Set the Contact Preferences to Work Address. Enter customer details, including an invalid or valid Canadian Postal
Code in the ZIP field.

5.

Click Create.

In this example, the invalid code D8K 1Q1 was rejected.

Limitations and notes

Edit validate rules provide only format checking. Many values that have the correct format (and so are accepted as
input) do not correspond to real Canadian Postal Codes. However, format checking can detect many input errors, and is
always better than accepting input without any checking.

The Submit operation for HTML forms strips off leading and trailing spaces. There is no need to test for them or to
match them.

Your Rule-Edit-Validate Java code should not accept a substring as a valid match.

WWW and other public sources provide regular expressions for book identifiers (ISBN numbers), telephone
numbers, email addresses, IP addresses, and many other patterns. Of course, you should test any expression you plan to
adopt to confirm that it matches your application requirements.

Consult the Help System topic "About the Regular Expression tool" for more information on the built in testing tool.

Like Java, the JavaScript language also supports regular expressions, so after you have implemented and tested
an edit validate rule, you optionally can extend validation to the workstation using the client-side format validation feature
and the standard ClientValidation HTML Property rule.

How to add a list-to-list control to a flow action form

Summary
A List to List control on a work object form allows a user to make multiple selections from one list of candidates. In this
example flow action from an auto insurance application,, a user selects safety equipment from the left list, each identified by
name, and clicks an arrow to add the selection to the right list. The right list identifies chosen safety equipment options; the
left list contains all of the available options.

Additional controls (unless disabled when the rule is configured) allow the user to sort either list, to remove previous
selections, to copy all or remove all selections. The user can make further changes until the user submits the flow action
form.
The List to List control is supported by two Page

List properties, one providing the list of source values and one

providing the list of destination values. As a result, the output of a List to List operation is not an array of text values (such as
can be stored in a Value

List property), but an array of embedded pages, identified by one visible text property such

as a name.

This article presents a step-by-step procedure for adding a List to List control to a harness, section, or flow action form. For
full details on all options, consult the Help system topic.

Suggested Approach
Preparations
Identify or create these parts of the List-to-List control:

The source property, a Page List property of class Code-Pega-List.

An activity or other processing to populate the source property.

A Single Value property within each embedded page that identifies the page, for display

The target property, also a Page List property, typically part of the work object. (The embedded pages of the
target property are often of the same class as the embedded pages of the source property, but this is not a requirement.)
Properties that are needed in the target embedded pages.

The source property structure matches those produced by the Obj-Browse, Obj-List-View, and RDB-List methods, but your
application can create the source property by any means.

Unlike the Dynamic Select control and AutoComplete control, the List to List control requires the source property to be
populated before the user sees the form containing the control.

Adding the control

To add a List to List control to a flow action, harness, or section rule:

1. Open the rule form. Select List to List from the Advanced control group.

2. Drag the List to List icon to a cell on the form, and drop it. The cell may change size
to accommodate the large control; you can adjust the size later.

3. Click the magnifying glass icon at the upper right of the cell to open the Cell Properties panel.
4. No changes are needed on the Field tab of the Cell Properties panel. On the Presentation tab, confirm that
the Format isListToList.

5. Click the magnifying glass to the right of the Format field to open the
Params pop-up window.

6. Complete the Params window. Identify the source property, the target
property, and the text property to appear in the source lists. Include doublequotes around property references if they contain a period character.

Optionally, enter two captions, to appear above the two lists.

Select Copy all properties if, when a user selects an item, the system is to
copy all properties on the embedded source page, creating a page with identical properties on a new embedded page with
the target property. Alternatively, you can define a from-to mapping and control which properties are copied.

By default, the left list displays at most 200 values, even if the source property contains more than 200 embedded pages. By
default, there is no limit on the number of pages that a user can add to the target property. You can change either limit
through parameter settings.
7. Click Save to close the Params window.
8. Optionally, complete other values on the Presentation tab and Conditions tab of the Cell Properties
panel.
9. Click Apply to apply the changes you made to the Cell Properties panel and Parameters window. Click OK to close the
Cell Properties panel.

10. Save the rule form.

11. Test. Ensure that your application populates the source property before the work object form (or flow action form)
appears.

A sample activity
This one-step activity creates a page SafetyEquipment of class Code-Pega-List. (Identify this page on the Pages

&

Classes tab of the Activity form.)

Whe
n executed, the clipboard contains a page for each piece of safety equipment.

Afte
r a user submits the flow action form, Process Commander copies pages from the source property to the target page. Six
selections appear as embedded pages to property pyWorkPage.Entrants.