Process

Enforcing business logic to your application process is done by creating business rules and applying
them to the use cases and workflow the application requires. Work and work items in a process flow
may need business logic applied to them for the process to continue or complete successfully.

Process Overview
PegaRULES Process Commander (PRPC) enables you develop and deliver business applications in a
completely model-driven environment. This approach makes it easy to directly capture, assess, refine,
and put into production process flows that precisely meet your business needs. At the core of these
modeling capabilities is the flow rule. In it, you use an easy-to-use diagram editor that provides a set of
modeling shapes, letting you graphically capture a business process and its components. The shapes
contain PegaRULES Process Commander business rules that define automated routing logic, declarative
and decision instructions, user work form and interface presentations, system and data source
integration, and other process elements. When you first build the model, you gain detailed insight into
the current process. As you research and analyze the model, you will likely discover tasks and
processing nodes that are impeding efficiency and productivity. As your team experiments with a
number of hypothetical configurations, you arrive at a process design that best meets your business
goals and resources. These modifications may include redirecting work paths, adding or removing
processing steps, or automating manual tasks. Because the process model is rule-based, you can
automatically implement the new design in your production environment and refine as necessary. Going
forward, you can make iterative updates to meet ever-changing business conditions and requirements.

What is a business process? | Key Features & Attributes | Terminology | Additional Information

What is a PegaRULES Process Commander business process?

A business process defines how a unit of work (a work item) moves until it is completed (resolved). In
PegaRULES Process Commander, a business process corresponds to a flow rule, which is associated
with a work item. A flow may define many optional detours, side trips, and branches reflecting decisions
reached along the way. The path that one item follows through the flow depends on its own
requirements, automatic decisions in rules, and on available resources. For example:

One home insurance application that fails to meet the automatic credit approval rules may require
special research, while others are handled automatically
An arriving customer service call in Mary’s territory may be routed to Tom, if Mary is unavailable
A request that is in a foreign language may be routed to a manager who can decide who among
his or her team is best qualified to handle the request.

Flows
Flows represent the fundamental business processes; they identify how work items are created, who
works on them, in what sequence, what decisions and processing occur automatically, and how the
items are resolved. Process Commander processes are represented by a flow within the Process
Modeler or a Microsoft Visio diagram. It contains a network of task shapes such as Assignment, Decision,
and Utilities, and connectors. These are associated with rules, parameters, or property values that
precisely specify how the shapes and connectors act upon the work object. Collectively, the
components define the process from the time a work object enters the flow until it is resolved. To
modify the process you edit the flow diagram. You can use the flow rule to run the process and to test
the results of your modifications.

Work items
A work item in a PegaRULES Process Commander flow is an electronic representation of a paper work
form. When an item is created, the system generates a unique work item ID and enters basic
information such as who created the item and when. As the work item (an insurance application, for
instance) moves through the process, operators or automated procedures add information to it. This
data is accumulated and stored on a system database for use in the current or subsequent
assignments. Operators can enrich the item's information content by attaching text files, screen shot
images, URLs or PDFs as the item moves through the process flow. PegaRULES Process Commander
automatically keeps a history of the item's progress, identifying operators that have worked on the item
and when, and what automated tasks were performed on it.
Flow example
This example below represents a purchase order request process. The employee enters purchase
requests for office supplies or equipment. Operators collect information about the the employee and the
items. Certain criteria must be met to continue processing. If not met, the request may be rejected. If
accepted, the item is submitted to an operator in the accounting group, where it is routed with through
the accounting process. When completed, the item returns to the purchase order process. Based on
data in the work item, an automatic procedure routes it either to a manager for approval or it is
rejected. When a request is approved or rejected, it is resolved and no further processing occurs.

When the processes starts, the system generates a unique work object ID for the new item. The
following processes can occur:

Users perform assignments, in Process Modeler, or in Visio,

which reflect the need for research, analysis, decision making, and data entry. Before the item
arrives at its assignment, the system performs automatic processes such as computing the goal
time and destination time, identifies any skills required or requested for routing, and determines
the individual operator or group of operators that is to receive the assignment. Rules within the
assignment promote compliance with deadlines or raises the urgency value when processing does
not meet these goals. When the operator's work is complete, the system saves the item to the
database, and may send email notifications to other individuals within the organization. The work
progresses to the next task in the flow.
A process may comprise multiple flows. To keep the diagram easy to follow, this flow is

represented by a Subprocess shape in Process Modeler, or a Flow shape in Visio

, which contains its own flow rule and diagram. In this example, the request is
processed in the accounting department before it returns to the purchase order process.
 Some tasks are performed automatically. For instance, decision logic to either route work to the

manager or to reject it is represented by a Decision shape or .

The Utility shape or uses a rule that automatically updates the

work item's history with a message indicating that the item has been fully processed and ends at

the End shape in Process Modeler or the FlowEnd shape in Visio.

back to top

Key Features & Attributes of a PRPC process

Flexible and adaptable rules built into each process help designers automatically adjust to new
information and criteria, eliminating manual interventions and workarounds. Because you can
understand how manual decisions have been executed and the conditions that apply to those decisions,
you can add rules to your process flow that automate the decision-making process.

Application Designers can evolve the process in small iterative-based parts at the individual rule level.
Java code is compiled and executed by the system at run-time, giving designers immediate feedback on
the effects of their changes. New configurations can be tested in real-time, even on production systems
without affecting other users or processes.

An intuitive graphical design tool provides insight to all members of the design team regardless of
technical expertise. The tool helps your team conceptualize and consolidate complex multi-stream flows
into one process. Because Process Commander modeling is rule-based, your design team can quickly
convert high-level designs into fully functional business processes that can be analyzed, refined, and
put into production with minimal IT support.

Using service connectors (such as SOAP, MQ, active file listening) you can connect your process to
existing enterprise applications, and pass data between systems that can be parsed, extracted, and
interpreted.

Rich work item information and automated tracking enable users and managers to dynamically monitor
work and take corrective action based on events to make sure work is processed on time and is running
optimally.

back to top

Important Terminology
Assignment — A point in the business process that requires human judgment and input. Flow
processing of a work item normally pauses when it reaches an assignment shape until a user completes
the assignment. The assignment normally appears on the worklist of the user who starts the flow.

Flow — A flow rule is the fundamental representation of a business process in Process Commander. The
rule defines the sequence of processing that your application applies to work objects. It contains a
network of shapes and connectors. They are associated with rules, parameters, or property values that
precisely specify how the shapes and connectors act upon the work object.

Straight-through processing — Business processes that can usually or often be performed

completely automatically, with no human intervention. A flow rule that contains no assignment tasks by
definition implements straight through processing. This represents a process with the greatest potential
to maximize efficiency and return on investment.

Screen flow — A flow rule that presents a user with a sequence of forms to complete. A screen flow
provides an effective way to simplify input processing and present questions or input fields in a series of
related forms. Users can change an answer to an earlier question by backing up in the flow; and, in
some situations, can complete steps in any order.

Shapes — Each shape in Process Modeler represents an Assignment, a Utility, a Decision, a Start or
End, and so on. (The Microsoft Visio presentation of a flow are informally known as a tasks.)

Work item — The primary unit of work completed by an application, and the primary collection of data
that a flow operates on. Operators using an application create, update, and eventually resolve and close
work items.

Worklist — A list of outstanding (not complete) assignments waiting for a user to perform them. The
list appears in a portal that supports application users that create, update, route, and resolve work
objects.

Workbasket — A queue of open assignments that are not associated with an individual operator.
Managers can review the assignments placed in a workbasket and distribute them one-by-one to
appropriate users for processing. Alternatively, the system can automatically reassign assignments
from the workbasket periodically to a user's worklist.

back to top

Additional information
Introduction to Process Definition | November, 2008

Running flow models | March, 2008

Flows - Concepts and terms | September, 2011

How to drag rules from the Application Explorer into shapes on a Visio flow diagram | November,
2008

How to perform bulk processing for a large number of assignments V6.1 | May, 2010

back to top

Design alternatives: multiple but smaller work objects or one

larger comprehensive work object
Summary
A developer asks: This is a design question around the issue of whether to have more small versus
fewer big work objects.

We're doing mortgage pricing. Each mortgage program has its own work type in the Process
Commander system. The number of mortgage programs that might be included as part of one
submission (button-click, web service, etc.) could range from two to almost a hundred. The two
approaches we're considering are:

Use a cover object that includes information about the submission as a whole (the Request Object),
and open multiple separate covered work objects to represent each necessary mortgage program
included in the single submission. This could result in many object creations and saves upon
submit.

Create the Request Object, but not as a cover object. Create separate pages for each mortgage
program included in the submission, operate as necessary on those pages, then copy each such
page back to the Request Object as an embedded page. This would result in many and complex
embedded pages being copied to the Request Object upon submit.

Is one approach generally preferable to the other?

Suggested Approach
The better practice in most situations is to create separate, distinct work objects. This is particularly
true if there's a likelihood that assignments could occur on the mortgage programs submitted, or that
reporting will be required.

Work objects offer extensive functionality, including assignments, history, attachments, and reports, for
example. Whenever feasible, your design should take advantage of such features.

The performance implications of saving multiple separate objects in the single submission do not differ
greatly from those of copying multiple complex pages to embed into a single work object. And the
multiple, smaller work objects will each be quicker to open and update subsequently than the fewer,
large objects.
Any reporting on the embedded pages of the fewer, large objects could require extensive indexing,
which is in itself a performance consideration - whereas the many, smaller objects will be more easily
accessed for reporting without requiring indexing.

Empty stub activities (extension points) are available for

work object processing
Summary
Starting in V4.2SP4, stub activities are available to enable your application to extend and override
standard work object processing . These have no steps, and are known as extension points.

The standard Work-. activities that call these extension points are mostly marked as final, so you cannot
override them.

For example, you can't override the Work-.New activity, but it calls Work-.NewDefaults, which is an
empty activity. Create an activity in your application RuleSet named MyWorkClass.NewDefaults to
extend the processing provided by Work-.New. Your activity, not the empty activity, is executed at
runtime.

Suggested Approach
V4.2SP4 includes the following extension point activities:

Work object creation

Work-.NewDefaults — called from Work-.New and Work-.NewCovered

Work item creation from AddCovered flow action

Work-.NewCoveredDefaults — called from Work-Cover-.ActionCreateCovered (pre-processing

activity)

Work-.AddCoveredDefaults — called from Work-.AddCoveredWork if parameter is set; parameter

passed in as true by Work-Cover-.ActionAddCovered (post-processing activity)

Cover manipulation

Work-Cover-.AddToCoverDefaults — called from Work-Cover-.AddToCover

Work-Cover-.RemoveFromCoverDefaults — called from Work-Cover-.RemoveFromCover

Assignment creation

Assign-.NewDefaults — called from Work-.NewAssign, Work-.NewAssignBasket (on the assignment)

To create settings for a specific assignment task in a specific flow, use the Assign- properties
pyFlowType and pxTaskName to identify it.

Review a work object

Work-.OpenDefaults — called from Work-.Open, Work-.OpenCover, Work-Cover-.OpenCover

Update a work object

Work-.UpdateDefaults — called from Work-.Update, Work-.UpdateCovered (and from the Open

activities above if read-only is not specified)

Perform an assignment

Work-.PerformDefaults — called from Work-.Perform

Asynchronous service call is interrupted by a ticket or service-level activity (ResumeFlow

usually)

Assign-Service.HandleInterrupt— called from RemoveAssignmentByTicket() function and

Assign-.CompleteAssignment activity

How to create a process that opens a portal from an

assignment link
Application users want to click an assignment link that opens the user portal directly, without SSO
credential challenge, at these contexts:

The assignment with the assignment open

The work object (Perform harness)

Problem scenarios
Two scenarios identified the need for the suggested approach described in this article.

CPM for Healthcare 7.4, PRPC 6.1 SP2

Users of Customer Process Manager (CPM) for Healthcare 7.4 running on PRPC 6.1 SP2 reported that
clicking an assignment link in email correspondence triggers an SSO credential challenge and takes
them to their worklists instead of directly to the CPM Service Object as they expect.

This problem does not occur with PRPC 6.2 SP1.

PRPC 6.3 SP1, Case Management

Users of PRPC 6.3 SP1 Case Management want to be able to create a case from an external application
using an HTTP Post request along with additional parameters and have the work object open in a tab of
the Case Manager portal. In PRPC 6.3 SP1, the harness of the work form opens without the portal.

Explanation
The Pega-provided activity ShowSelectedPortal calls only one other activity, ShowDesktop. The
suggested approach explains how to solve this problem, including how to add conditional logic that
opens the same portal from assignment links in both email and non-email modes.

Suggested approach
As an application developer, choose which development approach works best for your business users
who want to see linked-to assignments or work displayed immediately within the Case Manager portal
without SSO credential challenge.

Preview
How to create a process to open a portal from an assignment link
How to create a process to open a portal with the work object displayed on a tab

Preview
You work with the rules identified in the following table by rule name, rule type, and comments
describing what the rule does.

Rule
Rule Name Comments
Type

ShowAssignmentInPortal Activity Entry activity

ShowAssignment Portal Similar to the User portal

Similar to the User harness

UserOpenAssignment Harness Uses UserCenterPanelOpenAssignment instead of
UserCenterPanel

Modified to include a section that includes

UserCenterPanelOpenAssignment Section
CallOpenAssignment
 1. Reads the assignment handle stored in the pxThread
Rule page
Rule Name
CallOpenAssignment Section Comments
Type 2. Waits a second
3. Calls the openAssignment desktop API to open a new
tab for the perform harness

How to create a process to open a portal from an assignment link

The following example shows how to create a process that opens a portal from an assignment link.

1. The assignment link includes the entry activity ShowAssignmentInPortal.

This activity takes one parameter, AssignmentHandle.
The property pxThread.pxPortal tells the call to ShowDesktop that it will display the
ShowAssignment portal rule.
The assignment handle itself is stored on the pxThread page for future use.

2. The portal rule ShowAssignment is very similar to the User portal, with Spaces specified as follows:​
Space Name field value is Work.
Harness Class field value is Data-Portal.
Harness Name field value is UserOpenAssignment.
Default is selected.

3. The portal harness UserOpenAssignment looks very similar to the User harness, except that Center
Panel, Use Section field specifies the UserCenterPanelOpenAssignment section instead of
UserCenterPanel:

4. The portal section UserCenterPanelOpenAssignment, Layout tab specifies, at the bottom of the
form, Section Include [Data-Portal CallOpenAssignment]:
 5. The portal section CallOpenAssignment HTML for JSP is not auto generated, and the HTML Source
script is as follows:
<script><br />
var assignmentHandle = "<p:r n='pxThread.AssignmentHandle'/>";<br />
window.setTimeout ("openAssignment(assignmentHandle)", 1000);<br />
</script>

6. The CallOpenAssignment HTML Source script performs the following steps:

Reads the assignment handle stored in the pxThread page
Waits one second
Calls the Desktop API openAssignment to open a new tab for the Perform harness

In testing, we saw some issues when first-use assembly ran. Therefore, one second may not be enough
time. After first-use assembly ran, one second was sufficient. You might need to experiment with the
timeout value.

How to create a process to open a portal with the work object displayed on a
tab
As an alternative to opening the portal from an assignment link, use the following procedure as your
development approach to open the portal at the work tab:

1. Open a work object in review mode.

2. Store the work object handle in the pxThread page (Step 1 of the activity
ShowAssignmentInPortal).
3. Use the Desktop API openWorkByHandle (instead of openAssignment).

Find the openWorkByHandle API in the Pega Public API Package > Desktopwrapper.
Related GCS Case Object Number
KR-936, SR-73504, SR-93957, SR-74865

How to create a screen flow

Summary
A screen flow is a process flow rule that presents a user, such as a customer service representative
(CSR), with a sequence of forms to complete. Often each form has only a few questions to be answered.
The user completes the questions, submits the form, then receives another simple form with additional
questions. Depending on the configuration settings, presented questions may rely on previous answers
and the user may be able to go back to previous questions to review and possibly change their answers.
Screen flow harnesses allow you to configure the forms to appear in a variety of presentations.

To create a screen flow, you create a flow that calls the screen flow rule. A screen flow cannot be a
starter flow. The screen flow typically contains multiple assignment shapes that present information to
the user, along with other shapes. The scenario below explains how a screen flow is called from a
regular process flow.

Screen Flow Shapes

Screen flows have a limited set of allowable shapes. There are differences in functionality of some
shapes when used in a screen flow instead of a process flow. For example, the Split For Each shape has
only the Iterate processing mode. See How to use Split For Each shapes in screen flows and Developer
Help for more information.

Property panels for the allowable shapes in a screen flow contain an Entry Point checkbox. You must
check this box on at least one shape in a screen flow. When this box is checked, the shape is an entry
point to the process, meaning that processing can resume or begin at this point in the flow. This
checkbox also causes other fields to appear in the property panel, including the Only Going Back
checkbox that prevents users from jumping ahead without completing previous forms or steps. Once
the step is completed, the user can return to this point from the steps that follow.

Screen Flow Harnesses

You can present forms using one of three harnesses. Following are examples of each harness
presentation.

TabbedScreenFlow:

The TabbedScreenFlow harness presents the forms using tabs. At runtime, as the user completes the
questions and clicks Submit under Select Rule then Select Filters, for example, Set Fields becomes
active with a new set of questions. A checkmark appears on tabs the user has completed.

TreeNavigation:

The TreeNavigation harness presents the forms in a tree or list format, depending on the configuration.
Active form names appear in bold, and a checkmark appears by steps the user has completed.

PerformScreenFlow:

The PerformScreenFlow harness presents the forms in a breadcrumbs format. Completed form names
display in a blue rectangle. Active form names display in a larger font and with a pale-colored rectangle.

Suggested Approach
A hypothetical scenario helps explain how to create a screen flow in the
Process Modeler.
A company takes orders from customers over the phone. It is important that customers of this company
have a solid credit rating before the business relationship is established. The CSR first determines if the
caller is a current customer. If so, the customer information is confirmed, the order is entered, reviewed,
and submitted. If the caller is not a current customer, a subprocess using a screen flow guides the CSR
through creating a new customer account. The flow provides the CSR with small sets of questions
organized using a tabbed screen flow. The questions relate to contact, payment, shipping, information
and finally credit rating. The CSR can switch between the tabs to navigate among the questions as
needed.

Once the information is gathered, a determination is made as to whether a credit relationship can be
established. If not, the customer cannot be added and a follow-up rejection letter is sent. If the customer
is credit worthy, they are added as a customer and processing returns to the main flow so the order can
be taken, reviewed and fulfilled.

To accomplish this business processing, create a main process flow, OrderEntry, that creates the work
items, determines if the caller is a new customer, and if so, creates a subprocess,
CreateNewCustomer, that uses a screen flow process to guide the CSR through creating or rejecting
the new customer, then returns processing to the main flow. The flows look similar to the following
diagram:
Add the Subprocess shape to a main flow
1. Create the OrderEntry flow as shown above.
2. For the Subprocess shape, complete the rule form.
Use the name CreateNewCustomer.
In the Filter Flow Rule By field, select Screen Flow. This selection causes only screen flow
rules to appear when you use the SmartPrompt in the Flow Rule field.
Because the Flow Rule does not exist yet, enter the name of the flow you will create,
CreateNewCustomer. You can either continue creating that flow now by clicking the Open
Rule icon, or follow the steps in the next section to create the screen flow.
Check the Subprocess has Entry Points box. This is required for both TabbedScreenFlow and
TreeNavigation harnesses.

3. Save the flow.

Create the screen flow

1. Complete the fields on the Flow:New form. In this example, enter CreateNewCustomer in the
Flow Name field to match your entry in the Subprocess property panel.
2. In the Name field of the Template section of the form, use the SmartPrompt to select the
ScreenFlow template.
3. Click Create.
4. The starting flow diagram appears as follows:

5. Double-click the Start shape to view the property panel. In the Harness field, the
PerformScreenFlow harness is specified by default. Use the SmartPrompt to select an alternative
screen flow presentation, TabbedScreenFlow. You could also choose TreeNavigation. The
presentation to the CSR depends upon which harness you select in the Start shape.

6. Add shapes so that the flow is similar to the Subprocess screen flow in the diagram below. The
CreateNewCustomer flow includes four assignment shapes that present information in tabs to
the CSR. The name of the shape appears on the tab at runtime in the application.
 7. Mark each of the Assignment shapes as an entry point in the flow. In a screen flow, at least one
shape must be marked as an Entry Point. Typically, many shapes are marked. An entry point is a
place in the flow that a user can move to either by clicking one of the tabs or by clicking << Back,
which appears automatically at runtime in any assignment designated as as entry point.

Each task in the flow also presents at runtime with a Next button. When the user clicks the button, input
is validated and processing advances to the next assignment. For the last assignment in a
TabbedScreenFlow or TabbedScreenFlow, Next >> changes to Submit. For information on adding a
Cancel button, see the Help documentation, Editing in Process Modeler - Creating and Editing Screen
Flows.

Only one connector starts at each shape, and since that path is always followed, no additional
information is needed on the connectors.

The presentation of the CreateNewCustomer flow with each harness is shown below.

TabbedScreenFlow:
PerformScreenFlow:

TreeNavigation:

How to create an XPDL or BPEL representation of a flow rule

Summary

Using the Show Rule Data button ( ) you can display the XML underlying all rule forms. In addition, you
can transfer your process flow diagrams to other flow management systems by generating XML files in
these industry-standard formats:

Business Process Execution Language (BPEL) defined by OASIS

XML Process Definition Language (XPDL) V2 defined by the Workflow Management Coalition

This article describes how you generate these file from your flow rules.

Suggested Approach
Here is a sample flow rule diagram:
Here is Process Commander XML representation of the flow:

Use the XPDL and BPEL options located on the Design tab on a flow rule form.

Do the following:
 Click XPDL to generate an XPDL file.
Click BPEL to generate an BPEL file.

A dialog appears asking whether you want to save the file (default name export.xml) or open it in a
browser.

Here is a sample of the XPDL output:

Here is an example of the BPEL output:

How to create custom Visio stencils and shapes

Summary
When building a flow using Visio, you use shapes associated with Process Commander tasks, their
associated properties, and their behaviors. Optionally, you can create your own stencil containing
custom shapes. You can use such custom shapes to:

Conform to corporate standards

Match shapes that you use in other processing modeling tools
Associate one standard task type with multiple shapes. For example, you can create six shapes
that correspond to six kinds of assignments or six departments.

You can manually design the shapes in Visio, import image files, or mix shapes from Pegasystems
stencils, Microsoft stencils, or stencils designed by your company or industry group.

This article describes how you create a custom stencil, add shapes to it, associate them with flow tasks,
and upload the stencil into Process Commander.

Suggested Approach
There are three major steps in creating a custom template:

1. Create a new .vss Visio stencil file.

2. Add shapes to it and associate them with Process Commander tasks.
3. Upload the stencil into your Process Commander system.

Create a new template .vss file

1. Create a flow rule that you will use to create a new template.
 2. On the Design tab, click Edit Flow External to open Visio outside of Process Commander.

3. In Visio, select File > Shapes > New Stencilfrom the menu to create your new stencil. In the
example, the default stencil name is "Stencil2."

Note the red asterisk (*) in the header, which indicates that the stencil is in edit mode.

4. Click the header bar and save the .vss file in a local directory, using a file name of your choice
("OESstencil" here ):

Add shapes to your stencil

1. Using Visio drawing tools, create a set of convex, closed shapes to represent tasks. Using the
Standard and Format Shape toolbars, choose colors and shadows as desired. Alternatively, you can
add shapes by importing image files such as .gif or .jpg files. To import a file, select Insert >
Picture > From File (or Clip Art, Chart, and so on). Here is an example of a .jpg file called Utility that
 will be used in the new template:
2. Select the file and click Open.
3. When the shape appears on the Visio canvas, drag it onto the new stencil panel. By default, the
image is labeled "Master. n":

4. Drag the shape back onto the Visio canvas. By default, it has freeform properties.
5. To associate the image with an activity type, use the drop-down menu and select the appropriate
type (Utility in this example):

6. Click Applyin the Utility Properties panel. Note that you can specialize the shape by adding
properties and entering a meaningful name to indicate its purpose.

7. Turn on the Connection Point tool in the Standard Visio toolbar. Select the shape, and attach one or
more connection points as shown here:

Adding the connection points maintains the shape's association with the task and its properties.

8. Drag the image back to the new stencil pane, rename it as appropriate, and delete the original
 master shape.

9. Add more shapes as necessary. You can also copy and paste shapes from other stencils. Here is an
example showing a mixture of custom and standard Process Flow shapes in one stencil:

10. When you are finished, save the stencil and exit Visio.

Upload the stencil into Process Commander

1. Create a new binary file rule instance (Technical rule type) as shown here:

1. Enter webwb as the App Name (Directory). This is usually the location of standard Process
Commander binary files.
2. Enter a File Name of your choice.
3. Enter biw as the File Type (extension). (For technical reasons, when a stencil file is
incorporated in a binary file rule, the final key part of the binary file rule is biw.)
2. In the rule form, optionally enter a name of your choice in the Relative Path field to differentiate it
from the other .biw files in a list view.

3. Click Upload File.

4. In the Upload File window, click Browse and navigate to your new .vss template file.
5. In the Choose file window, rename the.vss extension to .biw. When the Rename warning appears,
click Yes.
 6. Select the file and click Open. The file and its path appear in the File Name field of the Upload File
window. Here is an example of the process:

7. Click Upload File in the window. A File uploaded successfully message appears.
8. Save the binary rule.
9. To use your new template in a flow, open the Designtab, use SmartPrompt to select the stencil, and
save the rule.

When you open the flow in Visio, your custom template and the standard Process Flow stencil will
appear in the Shapes panel.

How to track changed values of work object properties using

the Field Level Auditing gadget
Summary
The Field Level Auditing gadget allows you to configure individual scalar properties in work objects to
track for changes. Changed values appear in the work object history. .

This gadget automates the steps described in How to extend the security auditing feature to record
changes to additional properties by automatically creating the model and activity rules necessary to
record changes in the work object history.

Suggested Approach
To configure change tracking using the Field Level Auditing gadget:
 1. Confirm that the the application containing the property to be tracked appears in the header bar of
the Designer Studio. If not, select Switch Application > application from the application menu.

2. Access the Field Level Auditing gadget by selecting > Process & Rules > Work History >
Field Level Auditing.

3. Select the work type which has the property to be tracked. All work types in the current application
are shown.

Alternatively, select to view all properties currently being tracked.

4. Click the Add a Row button and select a property using the SmartPrompt.

5. Click Submit. The gadget creates (or updates) a model named pyTrackSecurityChanges in the
Work Type and RuleSet Version you specified. The gadget also creates (or updates) a Declare
Trigger rule that monitors the property for changes and adds records to the work object history.

6. To test, create a new work object. Any changes made to the value of the identified property, along
with the operator that made them, are reflected in the work object history.

How to view and update flow shape properties without using

Visio
Summary
You can use the flow shape viewer feature in the Diagram tab on a flow rule to quickly review and
modify rules and properties that comprise the flow without affecting the process diagram itself. In
addition, team members who do not have Visio on their desktops can take advantage of this
functionality.

This article describes how to use flow shape viewer.

Suggested Approach
The viewer enables you to:

Navigate to rules referenced by a shape

Edit the shape's flow properties
You can use the viewer with these flow shapes:

Assignment (flow action connectors are accessed in this shape)

AssignmentService
Decision
Integrator
Notify
Router
Spinoff
SplitForEach
Flow (subprocess)
Utility

Using the shape viewer

The following example illustrates how you use the viewer to open rules associated with a shape, and to
open the shape's properties panel.

1. Open a flow rule.

2. On the Diagram tab, select and right-click a flow shape. The shape viewer appears. In addition, a
golden arrow points to the selected shape as shown here:

You use the View tab to open referenced rules, and use the Edit tab to modify shape
properties.

3. To open a referenced rule instance, click its link on the View tab. For example, clicking on
Perform opens the harness rule used in the assignment.

Note: You open flow action rules leaving an assignment by clicking the Flow Action links on the
assignment shape viewer as shown above.

If you modify and save the rule, the shape uses the updated rule when you execute the flow. You do not
have to save the flow rule for your updates to take effect.

4. Return to the flow diagram. To open the shape's properties panel, click the Edit tab on the shape
viewer. The panel, which is the same one used in the Visio editor, appears. Here is an example:
 5. Review the panel information and modify it if necessary. You cannot modify the shape name.

6. Click Apply to keep your updates and leave the viewer open. Alternatively, click OKto apply your
updates and close the viewer.

You can only use the viewer with one shape at a time. That is, if the viewer is open and you right-
click on another shape, the original viewer closes and a new one opens. The original updates are
automatically applied.

7. Save the flow rule when you are finished with your design session. When you save, any changes in
an open viewer are applied.

To cancel your changes, exit without saving. A warning message appears indicating that there is
changed data (assuming that the Exit warning is set in General Preferences).

More about the shape viewer

As you work with the viewer, note the following:

You can move the viewer to any position on the flow diagram. Click the the pin icon ( ) to anchor
it. The viewer remains open in that position and updates are applied each time you right-click on
another shape. To close the viewer, unpin it in order to display the OK button or use the exit icon (
).
You can work concurrently with other flow rules using a viewer in each diagram. Switching
between rules does not apply viewer updates.
You cannot open a viewer on an unconnected shape (grayed out).

Introducing Process Modeler, an alternative to Visio for

creating and editing flows
Summary
The Process Modeler flow editor is available with V6.2 and newer. This new flow editor offers improved
usability and functional enhancements. The design offers a familiar user interface to developers who
understand flow editing in Visio and who have created or updated Section rules.

Process Modeler is the default flow editor for flows. However, if you prefer, you may continue to edit and
create flows in Visio. You can save existing Visio flows first created in V6.2, V6.1, or an earlier version
for editing in either Process Modeler or Visio. However, a flow saved using Process Modeler cannot later
be converted to Visio format.

The Process Modeler offers a new, yet familiar, look to shapes, based upon those found in Business
Process Modeling and Notation (BPMN). Some shapes that were available in Visio are eliminated, as
their functionality is built into other shapes.

Visio users who try the Process Modeler editor will find the transition straightforward. All the tabs on the
Flow rule form, other than the Diagram tab, are identical for both editors, and runtime execution is
nearly identical.

The flows below demonstrate the PurchaseOrder flow in the Visio editor, and that same flow converted
to Process Modeler editor.
In the converted PurchaseOrder flow below, the shapes and flow are easily recognizable in the Process
Modeler.

Maintaining the diagram and updating the property panels is an intuitive process. Connectors are drawn
from shape to shape on the canvas. Keyboard shortcuts simplify common tasks. Further information is
available in the Developer Help.

To understand the differences and similarities between the two editors, review these topics:

What's different with shapes?

 Connector
Spinoff
Fork
Notify
Router
Ticket
Comment/Annotation

Toolbars

Process Modeler toolbar

Visio toolbar

Working with Visio flows

Continuing to work with existing Visio flows

Converting a Visio flow to a Process Modeler flow
Creating a new Visio flow

Other differences

Keyboard shortcuts

Suggested Approach
What's different with shapes?
Shape names can contain spaces and are no longer limited to characters and digits. You can even
use foreign character sets.
You can change the name of a shape by clicking it, then typing the new name in the highlighted
field. You do not need to open the shape property panel.
Rather than the shape stencil on the left panel in Visio, shapes are added using the Flow Shape
palette button on the toolbar or by right-clicking the canvas to display an Add Shape menu.
To open the primary rule associated with a shape, right-click the shape. From the drop-down menu
on an Integrator shape, for example, you can select Open Activity. For an assignment shape, you
can select Open Harness.
Starting with PRPC 6.3, shapes have a Status tab that allows you to easily change the status at
multiple points in the life cycle of a work item without adding a utility shape to the flow for each
status change.
Starting with PRPC 6.3, the Assignment shape has the Optimization tab that allows you to select
one or more properties to use for process optimization.
One of the more noticeable differences between Process Modeler and Visio is that there are fewer
shapes in the Process Modeler. The functionality of all the shapes in Visio has been retained and
often enhanced. However, to better streamline flow interaction and to be more consistent with the
BPMN standard, some shapes are now combined with other shapes. Specifically, the following
shapes, explained below, no longer appear on the shapes palette:
Connector
Spinoff
Router
Ticket
Fork
Comment

Connector

Draw connectors using click-and-drag from one shape to another in Process Modeler. Each shape has
pre-defined connector points. The connector may be drawn to and from specific connector points,
creating an "anchored" connection. The connector will stay on anchored points, regardless of where the
shape is moved on the canvas.

The connector may also be drawn to or from the arrow in the middle of the shape, creating an
"unanchored" connection. The connector will attach to the best or closest connection point as a shape is
moved.

A connector must be drawn to and from a valid point in order to appear on the canvas. An invalid
connector will not appear.

Toggle Likelihood display on and off using the on the toolbar.

Spinoff

The functionality of the Spinoff shape in Visio is built into the Subprocess shape in the Process Modeler.
In the Subprocess Properties panel, the Subprocess tab contains a Spinoff Flow checkbox to indicate
that a subprocess flow executes as a spinoff flow while the current flow continues to execute.

A subprocess that runs as a spinoff flow appears with the spinoff arrows icon.

Fork

The functionality of the Fork shape in Visio is built into the Decision shape in Process Modeler. In the
Decision Properties panel, the Decision Tab contains the Type drop-down menu that provides a list of
available decision types. Select Fork from the menu. The outbound connectors from the Fork type
Decision shape contain information about the branches.

Notify

The functionality of the Visio Notify shape is built into the Assignment shape in the Process Modeler. In
the Assignment Properties panel, the Notification Tab contains the Notify field where you use the
SmartPrompt to select the Notify activity.
An Assignment shape with Notification appears in the flow with an envelope icon.

Router

The functionality of the Visio Router shape is built into the Start shape for screen flows, and into the
Assignment shape and Swimlanes for regular process flows in the Process Modeler. The Swimlanes
Properties panel contains the Swimlane tab with a Router field where you use the SmartPrompt to
select the Router activity.

In the Assignment Properties panel for process flows and the Start Properties panel for screen flows, the
Routing Tab contains the Router field where you use the SmartPrompt to select the Router activity.

If you are using Swimlanes, the Router assigned to the Swimlane overrides the router assigned to an
assignment.

Ticket

The functionality of the Visio Ticket shape is built into all shapes in the Process Modeler that allow
tickets:

Assignment
Assignment Service
Decision
End
Integrator
Spinoff
Split Join
Split For Each
Subprocess
 Utility

The Properties panel for each shape has a Tickets tab where you select the ticket to set on the shape.

A shape with a ticket assigned appears in the flow with a triangular ticket icon.

Comment/Annotation

The Comment shape in Visio is replaced by the Annotation shape in Process Modeler. Comments in Visio
flows will not be preserved when the flow is converted to Process Modeler.

Toolbars
Process Modeler Toolbar

In Process Modeler, the toolbar is arranged differently from the Visio toolbar. Controls on the left side
allow you to interact with the process flow, while controls on the right side let you control your view.
Functionality has been added, including access to the Flow Shape palette, the ability to control the
display of likelihood on connectors, shape alignment, grid snapping. The function of each icon is
described below, and further information is available in the Developer Help.

Icon Function
View shape properties
Preview harness of selected Start or Assignment shape
Delete selected item

Flow Shape palette

Pan mode
Select mode

Shape alignment mode

Grid snapping mode

Likelihood display on connectors

Orient swimlanes horizontally

 Icon Orient swimlanes vertically
Function

Draft mode is off

Draft mode is on
Display metrics options

The right side of the toolbar allows you to select the a view of Process Modeler or the Discovery Map. If
you have created or opened a Visio flow, a Visio button will also appear to indicate your current flow
editor.

Visio Toolbar

In Visio, the toolbar displays differently as well. The function of each icon is described below.

Icon Function
Display Visio toolbar
Undo
Zoom in

Zoom out

Draft mode is off

Draft mode is on

Working with Visio flows

In this section, you learn about:

Continuing to work with existing Visio flows

Converting a Visio flow to a Process Modeler flow
Creating a new Visio flow

Continuing to work with existing Visio flows

You may continue to work with existing Visio flows. When you open the process flow, you will see:

On the right side of the toolbar, Visio is the selected view. On the left, use the icons to open the flow
using Visio:

— opens Visio in the current window

— opens Visio in an external window
When the flow is opened for Visio editing in an internal window, you see the new toolbar icons,
explained above. Editing, saving, and closing functions remain the same.

Converting a Visio flow a to Process Modeler flow

You can convert an existing Visio flow to a Process Modeler flow. Once you have converted and saved
the flow with Process Modeler, you edit the flow with Process Modeler going forward. You cannot return
to Visio editing on this flow.

With a Visio flow open, click . The Visio flow converts to a Process Modeler flow. Edit the flow
as desired.

When you save the flow, a warning message informs you that once you save this flow in the Modeler
view, it can no longer be viewed or edited with Visio. You can continue with the Save or click Cancel. If
you cancel, you can click to discard any edits made in Process Modeler and continue editing
the flow using Visio, or you can simply close the flow. When you next re-open the flow, Visio will be the
flow editor.

Comments in Visio flows will not convert to annotations in Process Modeler. Re-enter comments as
Annotations.
All connectors in the converted flow will have unanchored connections.

Creating a new Visio flow

Process Modeler is the default flow editor. However, you can still create new Visio flows. On the Flow:
New form, select VisioFlow or VisioScreenFlow in the Template field.

For a tabbed screen flow, open the property panel on the Start shape and enter TabbedScreenFlow in the
Harness field.

Other differences
Swimlanes and Pools

Swimlane behavior in Process Modeler differs from behavior in Visio in that:

Assignments are dragged onto a swimlane in Process Modeler. You cannot drag a swimlane onto
an assignment.
The Swimlane uses a default router of ToCurrentOperator. The assignment will always use the
 Router assigned by the Swimlane.
A flow diagram has one pool only.
When you add Swimlanes to a pool, they appear at the end of the pool and may be repositioned, as
needed.
When you delete a pool or a Swimlane, the shapes contained within do not get deleted. Rather,
they remain on the canvas.

Minimap

The minimap, in the lower right corner of the Process Modeler canvas, allows you to pan, using click-
and-drag, around a flow that is larger than the window. Click the square in the lower right corner of the
minimap, then drag to zoom in on an area of your process flow.

Templates and Screen flows

Three templates are available when you create a new flow: ScreenFlow, VisioFlow, and VisioScreenFlow.
Older templates are still accessible.

Screen flows are created using a template. On the Flow: New form, select ScreenFlow or
VisioScreenFlow in the Template field.

For a tabbed screen flow, open the property panel on the Start shape and enter TabbedScreenFlow in the
Harness field.

Application Explorer Drag and Drop

In Process Modeler, you cannot drag a rule from the Application Explorer onto the canvas.

Flow filter

When editing a process flow, the property panel for Subprocesses, Split Join and Split For Each shapes
allows you to filter flow rules by Screen Flows or Process Flows. When you edit a screen flow, only
Screen Flow rules can be chosen.

Data Transform Rules

Use a data transform to:

Define one or more initial properties and property values for instances of a class.
Map properties (and their values) of an instance of a class to an instance of a different class, or the
same class.

Using a data transform, rather than setting the property values one-by-one in an activity, improves
runtime performance. Consistency is also improved when a data transform rule is re-used. Data
transform rules speed development, because you can set values for many properties quickly in a single
form.

WhereAmI?
In the WhereAmI display, the Process Modeler flow image is vector-based, allowing you access to
navigational tools such as pan and zoom.

The Open Folder button in the left panel for Visio flows is replaced with the Open icon beside the flow
name in Process Modeler.

The selected flow name displays in bold text rather than yellow highlight.

Keyboard Shortcuts
The following keyboard shortcut keys are available in Process Modeler:

Shortcut Key Function

+ (on numeric keypads only) Zoom In
- (on numeric keypads only) Zoom Out
Delete Remove the current shape or connector
Ctrl a Select all
Left-click, Ctrl and move Turns off alignment guides for the current shape move operation
Left-click, Shift and move Constrains shape movement to current X/Y plane

Introduction to Process Definition

Summary
A business process defines how a unit of work (work object) moves until it is resolved. In Process
Commander, a business process corresponds to a flow rule, which is associated with a work object.
Your application may comprise one or more flows.

Process Commander associates a flow rule with a Microsoft Visio diagram, which graphically represents
a process. The diagram contains a network of shapes (tasks) and connectors (arrows). They are
associated with rules, parameters, or property values that precisely specify how the shapes and
connectors act upon the work object. Collectively, the components define the process from the time a
work object enters the flow until it is resolved. To modify the process you edit the flow diagram in Visio.
You can use the flow rule to run the process and to test the results of your modifications.

Note: Begining in PRPC 6.2, you can define flows using Process Modeler, a browser-based tool, rather
than Visio. See Introducing Process Modeler, an alternative to Visio for creating and editing flows.

Defining your process

Defining your process is the result of answering fundamental questions as they regard your business
requirements. Here are a few basic ones:

What tasks are needed to be performed on a work object?

What is the sequence (work flow) in which the tasks occur?
What actions will be performed when a work object is assigned to a user, who will do it (a specific
operator or any operator with access to the work), when must it be completed, and what choices
will the operator have when the actions are completed and must be sent to the next task in the
process?
Should an assignment be automatically routed to an operator other than the current one based on
specific criteria such as skills, backlogs, facts in the work object, urgency, deadlines, and so on?
Should some tasks be automated at points during processing such as sending correspondence,
updating a work object's status, or finalizing a work object for resolution?
Should some decisions be automated based upon computations and comparisons that cause
processing to continue along one path or another?

This article provides an overview of how you define a process in Process Commander and the tools you
use to meet your design objectives. The topics include:

Locating your flow rule and opening the flow diagram in Visio
Understanding flow shapes and the tasks they perform

Defining how a shape performs its task

Understanding commonly used shapes
Executing a flow to test your process design
Using Visio editing tools
Suggested Approach
To locate and open a flow rule, you can use either of the methods described here.

Double-click Flow in the Application Explorer to display all the flow rules in your application, which
are listed in the Process category.

Click the appropriate flow rule from the list to open the rule form.

Use the Process slice in the Developer portal to open flow rules that you are likely to be working on
as follows:

1. Click the Process slice icon.

1. When the Processes and Subprocesses section appears, select Explorer in the Process drop-
down list. A section opens containing one or more buttons, each of which is labeled with the
name of a flow rule in your current work pool (which contains all the work types to which you
have access). In this example there is one flow named Purchase Order.
1. Click the button to open the flow rule.
The flow rule displays the flow diagram on the Diagram tab.

Example of a process
The flow in the above example defines a purchase order request process. The employee enters
purchase requests for office supplies or equipment. Operators collect Information about the the
employee and the items. Certain criteria must be met to continue processing. If not met, the request
may be rejected. In some cases, requests must be approved by a manager. When a request is approved
or rejected, it is resolved and no further processing occurs.

This article uses the above flow to describe a typical Process Commander process definition and how it
can be modified to meet your business requirements.

Before you begin

Before you begin editing a flow, click the Process tab on the rule form and make the following settings
(if not already set):

1. Check the Creates a new work object option so that when the flow starts, a new work object,
which is uniquely identified, is created.
2. Select New in the Harness field. This ensures that a new work harness is used when the new work
object is created.
3. Select pyDefault in the Model field so that standard property values are used to populate
information about the new work object.

Opening the flow diagram in Visio

To open the diagram in Visio and begin editing, click the Flow Editor icon on the Developer toolbar.
Here is how the diagram is displayed in Visio:
Building blocks: Flow shapes and connectors
The Shapes palette named Process Flow contains the shapes you use to build your flow. Each shape has
a descriptive text name.

The shapes identify types of tasks. Drag a shape from the palette into the Visio workspace to add them
to your flow.

The following table lists the shapes and describes the tasks they perform.

Shape Description

Assignment — Creates an assignment task associated with work object in a workbasket or

worklist. The task must be completed by a person or the system before the flow can progress. It
represents a pause or potential pause in the flow.

Optionally, after the assignment task is defined, you can associate a service level rule with it. A
clock appears on the diagram, as shown here.

Assignment-Service — Passes control to an external system (for example, using a Connect

BPEL rule). Flow execution pauses until Process Commander receives a service request of the
appropriate type.
Shape FlowStart — Identifies the start task of this flow. Every flow has one Start shape.
Description

Comment — Adds explanatory text comments anywhere on the flow diagram. Comments do
not affect execution of the flow.

Connector — Associates a task in the flow with another that may follow the first task.
Connectors leaving assignment tasks may be flow actions. Connectors leaving other tasks such
as decision or utility shapes may be when conditions.

Decision — Identifies an activity that can make an automated decision about the progress of
the work object through this flow.

Flow — Identifies a subflow, which is a flow rule that is referenced in another flow. For
example, add a Flow shape to the your flow rule to start another flow and end processing of the
current flow. The second flow is called a subflow of the first flow.

FlowEnd — Marks the end of the flow. When processing reaches this shape, no further
processing by this flow happens. A flow may contain none, one, or multiple FlowEnd shapes.

Fork — Supports automatic selection of one connector from two or more.

Integrator — Identifies an activity that can connect to an external system to send or receive
data.

Notification — Notifies a work party by email or correspondence about the status or progress
of this work object as the assignment is created.

Router — Sends an assignment to a user, workbasket, or agent other than the current user.
Associate a Router task with an assignment task. This activity determines which worklist or
workbasket is to contain the assignment.

Spin-off — Starts a new flow execution and does not wait for its completion.

Split-Join — Sends the work object to two other flows, both of which must complete before the
current flow resumes.

Split-ForEach —Performs an operation or test on each element in a repeating group.

Pools and swim Lanes — Identifies and groups tasks performed by separate organizational
units within one division.

Ticket — Marks a business exception that might arise at any point in the flow, such as a
cancellation.

Utility — Specifies an activity to run at that point in the flow to perform automated processing
without any user assignment.

Defining how a shape performs its task

When you drop or select a shape on the Visio workspace, the corresponding shape properties panel
appears in the top left corner. You use this panel to name the shape and associate it with a set of
characteristics that define how you want a shape to perform its task. These can include flow action or
decision rules, and other information such as field values, properties, or parameters.

Here is an example of a connector properties panel for a flow action leaving an assignment:

The connector is defined by a flow action rule (Submit) and a parameter (Likelihood). The star icon ( )
indicates that the field is required. Here is the associated flow action rule.

Other fields such as Application and Work Type may be entered by the system based upon rule settings
or properties located elsewhere in the application.

From the properties panel, you can edit rules that display an edit icon next to it. Click on the icon to
open the rule and modify it. You can also create new rules (ones that do not yet exist) from the panel.
For example, you could delete Submit in the Flow Action field, enter the name of a new rule , and click
the edit icon to open a new rule dialog.

Executing a flow to test it

During your flow design session, you can test the process by saving the diagram and clicking the Run

toolbar button or use Ctrl +R as a shortcut.

Note: If you use either of these methods while in the flow rule, you are prompted to create a test page
and use the pyDefault model. Click the Reset page & Run flow button.

If you are not working on the flow rule, you can select Run > Process > (your flow rule) from the
Developer portal at any time.

If the results are not what you expected, modify the rule and run it as many times as necessary, testing
each possible path. Use the gold Where-Am-I? arrow to see where an assignment is located in the
flow.

Using draft mode and flow modeling

When designing and testing, you can turn on draft mode . In this mode, the flow rule is known as a
flow model. Flow modeling lets you run flows during the development cycle without having to
associate rules with shapes. For more information, see How to create and test a flow model.

Note: You cannot test a flow rule that has Availability set to No/Draft Mode.

Set the Available field to Yes, even if the Visio draft mode is in force.
Understanding the basic shapes and how they work
The shapes and their tasks that you will probably use most frequently include:

Assignments (and their flow action connectors) — Define the following:

Who performs the action on the work object and what actions must be performed
What actions can be performed by the user
When the assignment must be completed
Which path the work object takes when the assignment is complete
What updates can be made to the work object without advancing it in the flow
Router — Computes or derives a workbasket or Operator ID name and sends a new assignment to
that workbasket or to a user worklist. A router is always associated with an assignment.
Decision — Automates decisions based on the inputs from the flow and work object.
Utility — Automates processing tasks (no user interaction or input).
Connector — Connects two tasks. The behavior of a connector depends upon the shape it is
leaving . For example, connectors leaving an assignment typically represent flow actions that
determines where the the work object is sent when the assignment is complete.

Assignment — This is the core shape in almost every flow. It represents a user's analysis, research,
data input, and decisions that cause the assignment to be completed. In conjunction with their
connectors, which represent flow actions, assignments represent the stepping stones on the process
path. For this reason, pay special attention to how you configure assignments so that your design
results meet your objectives. In addition, because the process will stop if an assignment is not
completed, you must be careful to account for flow prerequisites and contingencies such as insufficient
data, or incoming or outgoing processing conflicts that may impair performance.

Who performs the action on the work object and what actions must be performed?

An assignment assigns work to individuals or to an automated process based upon the rule
you select in the Rule field in the Assignment properties panel. In almost all cases, you send
the work to an individual operator's worklist or to a workbasket that is shared among an
access group associated with multiple operators.

When an operator opens the work object in their work list or basket, a work object form is
displayed. You use harness rules to define the appearance and processing of work object
forms used in your application. Process Commander includes more than a dozen standard
harness rules, which you can customize to extend and tailor them to your specific needs.

You specify which harness rule to use with an assignment in the Harness Purpose field in the
Assignment Properties panel.

Here is an example of the Perform harness rule used with the Item Entry assignment. It has
been customized using other rules such as sections and properties to suit the required tasks.
When must the assignment be completed?

An assignment can have an associated service level rule, which tracks the time that has
elapsed from when it was assigned until it is completed.

Clicking the Open icon displays the rule, which specifies that the manager's goal is to
complete the approval action within 2 hours of receiving the assignment. As time passes, the
assignment's urgency is escalated. Another task (such as reassigning the assignment) may
automatically be triggered as a result.

Which path will the work object take when the assignment is complete?

You associate flow action rules with assignments to specify the choices available to users as
an interim or final disposition of an assignment. Each flow action indicates the likelihood it will
occur when the assignment is completed. Flow actions are represented in the flow diagram as
connectors leaving an assignment.

For example, an operator in the Item Entry assignment gathers information about the items
ordered (names, quantities, and prices) and the requestor's information (department name
and number). For example, if the the employee requests 20 laptops, the operator can choose
to reject it based on a company policy to send requests of this size through another purchase
process.

A flow actions is usually associated with a likelihood value or percentage between 1 and 100.
Typically this is a before-the-fact opinion about the estimated percentage of times users are
expected to choose that flow action during the process.

In this example, there are two flow actions. the user at the Item Entry assignment can either
submit the request (likelihood of 90%) or reject it (likelihood of 10%).
 Flow actions may require different input fields and may use different form displays. In this
case, the reject flow action has its own work form. Flow actions contain HTML that displays to
the user in the Take Action drop-down box of their assignment work form (Perform harness) as
shown here:

The layout of the Reject work form is designed in the Reject flow action rule. The text from
Short Description field appears in the Take Action field.

The order in which the flow actions appear depends upon the flow action likelihood
percentage (. In the above example, Enter Order Items appears first because the likelihood of
the Submit flow action is 90%.

How can a work object be updated without advancing it in the process?

You can also use flow actions to update a work object without advancing it to the next task in
the process. These updates may include attaching a note to the work object, or attaching a
file that enables the user to browse for and attach a file from an outside data source. You use
the Local Action section in the Assignment Properties panel to select one or more standard
local actions, or you can create one to meet your needs.

Local actions appear in the user interface as shown here:

Router — To send newly created assignments to a destination other than the default ( the worklist user
who originated the work for example), you attach a router to an assignment shape. For example, you
can send an assignment to an operator based upon availability, switch a worklist assignment to a
workbasket, or send an assignment to a specific operator based on the operator ID.

A router's behavior is governed by an activity rule. Activities contain instructions that automate
processing through a sequence of steps. During processing it usually references other rules to perform
its tasks. In this example, the router uses an activity called ToManager.

The router sends the assignment to an operator based on his or her operator ID. In this case it is
[email protected].

Decision — Automating flow decisions can significantly enhance overall process performance. It
eliminates the need for an operator to review relevant information about the work object and decide
which path it should be sent to based upon a set of business conditions or criteria. A decision shape is
associated with a decision rule such as a decision map, tree, or table, or you can create your own
Boolean expression. The decision process you choose uses the appropriate logic to compute an
outcome based upon property values associated with the work object.

In this example, the decision shape is associated with a decision tree rule named
OrderTotalNeedsApproval.

The path taken from the Needs Approval shape is based upon the outcome of the decision and the
values in the connectors leaving the Decision shape.

The rule uses a logical statement so that if the request total (an amount computed by the system based
on data entered in the work form) is greater than $100, the outcome is True.

Therefore, a request with an order total value of $1000 will produce an outcome of True and follow the
process path leading to the Manager Approval assignment.

Utility — Automating certain processing steps can also contribute greatly to process efficiency. A utility
updates or performs tasks on a work object without human interaction before advancing it to the
appropriate path. Standard utility processes include:
 Attaching correspondence to the work object (a request in this case)
Sending correspondence
Saving it as an attachment to the request
Changing the status of a work object (not the status of an assignment)
Adding a record of this change to the history of the request.

In this example, the Update Status Completed utility uses an activity named UpdateStatus, which
automatically sets the request status to Resolved and writes this on the request's history record. In
addition, the system updates properties related to the work object so that processing can be finalized.

Most Utility shapes have one connector leaving it. When the Utility tasks are completed, the work can
advance on only one path. In some cases, the work object can advance on two or more paths based on
the outcome of the update.

In this example, the connector always advances the work object to the Set Confirmation Note utility, as
indicated in the Connector Properties panel.

The utility simply appends a text note to the work object's record indicating why it is resolved (either
completed or rejected). The request process is complete and no further processing occurs.

Using the Visio editing tools

The Flow editor provides other tools to make your design session easier. To open these tools, use the
following tool buttons in the Visio toolbar:

Button Description

Turn on or turn off draft mode. While the flow rule is in draft mode it is known as a flow model.
You can reference rules and flow actions that are not yet defined.

When a flow is saved in Draft Mode, Process Commander validates whether rules exist for each
shape in the flow. A warning ( ) image marks an incomplete shape and appears on the
property panel next to the parameter in error. Hover over the shape to display the error
message.

You can execute a flow rule in draft mode in systems where the production level is set to a
value less than 5.

Display the normal Microsoft Visio toolbars, to access full Visio features for drawing, shape
alignment, colors, and so on.

Click once to display the toolbars. Click again to hide the toolbars.

Save an editing session and remain in Visio.

When you save, Process Commander validates whether all shapes on the diagram can be
reached through connectors that leave either the Start shape or ticket shapes. It marks any
unreachable shapes with a gray background rather than a colored background. Incomplete
Button shapes are marked in red to indicate an error. Click the shape to review the error message. An
Description
error indicator ( ) also appears on the property panel next to the parameter in error.

Zoom in to enlarge the Visio diagram.

Zoom out to shrink the Visio diagram

Undo the most recent Visio operation (equivalent to pressing CTRL + Z ).

Exit Visio editing and return to normal rule form editing. The system automatically uploads
your results from your workstation to the new or updated flow rule and changes the toolbar. As
you exit Visio, Process Commander checks the diagram and highlights any dangling
connectors.

Introduction to Work Parties and Work Party Rules

Summary
This article introduces work parties and work party rules:

Understanding work parties

How work objects are displayed and selected in a New work object form
How to locate work party rules in your application
How to create a work party rule
Understanding work party data classes and properties
How to add work parties to work objects within assignments.
How to use work parties for routing work
How to identify work parties associated with a work object

What is a work party?

A work party is a person, organization, or business that is involved in some way with the progress or
status of a work object. The system associates the data defined in a work party rule with a work object,
which can have multiple work parties. Using work party rules makes it easy to capture and store this
information in your work object.

When you create your work party rule, you specify party roles. Roles identify why a party is present,
and may determine which properties are defined for that party. Roles are associated with pre-existing
classes. Their properties can be used to define the user interface and the storage location of work party
role information within the work object.

There must be one role designated as the originator (the party who directly caused the work object to
exist). Most roles are categorized as interested parties. This typically means that they are kept
informed through correspondence as the work object progresses to completion. Correspondence can
include email, mail, or phone text.

For example, a work object for a customer complaint may contain these party roles:

Customer (a person)
Customer service representative (an employee of your organization)
Customer's spouse
Customer's lawyer
Your organization's lawyer
A vendor involved in the complaint

In this example, it is likely that the customer is the originator party.

How work parties are displayed in a New work object form

The standard Work-.Newharness rule includes these section rules:

CoreParty — Contains a drop-down list of work parties associated with the work object.

PartyDisplay— Displays fields for collecting data defined for each work party.
Here is an example of how the work parties appear at runtime in the drop-down list on a new work form:

Selecting any one of these roles displays fields for collecting information about the role as shown here
for DeptManager:

How to locate the work party rules in your application

You can locate work party rules using either of the following methods:

Cases and Content slice ( ) — Click the icon on the Developer portal to access a summary
report of the the work party rules that apply to the work types in your application. Select Summary
from the drop-down list to display the report.

Application Explorer — Located in the Process category, double-click on Work Parties to display
a list of all the rules available in the current application:

How to create a work party rule

To create a work party rule, do the following:

1. In the Application Explorer, right-click on Process and select New > Work Parties.
A new Work Party rule dialog opens.

2. In the Applies To field, use SmartPrompt to select your desired work type. Enter Default in the
WorkParty field.

3. Click Create.

A work party rule form appears. Here is a sample of a completed rule form that is used for the New
Purchase Order work form example shown above.

The rule form contains the following fields on the Valid Parties tab:

Field Description

Enter a party role that will appear on the CoreParty section on the work form. It must not
Role
contain spaces or underscores.

Select a class derived from the Data-Party class, which are intended for work parties. For
Party example, you can enter Data-Party-Person for a customer role and Data-Party-Operator
Class for Process Commander users. In the above example, Employee is associated with Data-
Party-Operator and Accounting

Optionally, you can enter a short description of the Data- class. This description appears
next to the party role on the work object entry form when you execute the flow.
Party
Prompt
For example, you can enter Real Estate if the class distinguishes Real Estate Lawyers from
Family Lawyers. On the work form, you will see Lawyer — Real Estate.
 Field Optionally you can use a model rule to cause the system to complete initial values for some
Description
Model fields on the PartyDisplay section.

Select the VOE (Visible on Entry) check box to cause the PartyDisplay section for this work
party role to appear when the work object entry form first displays. For example, you can
require that the originator is automatically displayed. If not selected, the user must select a
VOE?
role from a selection box.

In the above example, Employee is visible on entry.

Select to indicate that this party must be present in every new work object. This is usually
selected for the originator.
Required?
In the above example, Employee (the originator) is required.

Entering a party role in one or more Party fields lets you enter information for multiple
instances of that role. For example, if you enter party role "Dependent" in the Party field,
List
you can repeatedly open a PartyDisplay section for the role and collect information for each
Parties
That May dependent. By default, you can enter information in only one PartyDisplay section for each
Repeat role.

In the above example, none of the roles can repeat.

Work party data classes

You can use data classes derived from the Data-Party class to organize your role and work party data
into meaningful categories. Using sub-classes enables you to produce reports based on their classes.
You can also associate each class with a model that defines the initial properties you want to include
when you design the PartyDisplaysection rule. The system is delivered with five standard Data-Party
sub-classes as follows, which include example definitions for each:

Data-Party-Com — Business organizations

Data-Party-Gov — Government organizations
Data-Party-Operator — Process Commander users (who have Operator IDs)
Data-Party-Org — Nonprofit organizations
Data-Party-Person — Parties who are not Process Commander users

You can create your own sub-class and an associated model.

About work party properties

The inherited property .pyWorkParty is defined in your work class as a Page Group of Data-Party. This
property holds the details of each work party associated with your work object. You specify the roles
(uniquely identified by the pyWorkPartyURI) and other property types commonly used, such as
pyLastName, pyFullName, pyAddress, and so on. You can create custom properties for your Data-Party
or sub-classes if necessary.

To help you capture information about work parties who are directly involved in processing the work
object within the system, you can use standard properties in class Data-Party-Operator such as
pyUserIdentifier, pyUserName, and so on. These are included in the CurrentOperator model.

How to add work parties to an existing work object

In most cases, you add work parties and associate them with the work object when it is created.
However, you can use the AddParty flow action to add new work parties (from those already defined in
your work party rule) using a flow action within an assignment. For example, here the flow action is
added to the Confirm assignment:
Here is how the local flow action appears in the work form when the work reaches the Confirm
assignment:

How to route assignments to work parties

You can route an assignment to a work party within a Router shape using the ToWorkParty rule and
naming the party as the parameter.

In this example, the assignment is routed to the SalesManager work party (the role is listed in the work
party rule):

Note that the recipient work party must have the ability to interact with the work object (for example, a
user within the work pool and an operator ID that is enabled to receive work).

How to identify work parties within a work object

When testing applications, as you advance a work object through a flow, you can access the clipboard
to identify the work party and the associated properties associated with the object. The pyWorkParty
Page Group property is listed on your work object's pyWorkPage .

In this example, this work object is associated with the EntryOperator work party in the Data-Party-
Operator class. The properties associated with the class are listed in the Single Value properties panel.

Running flow models

Summary
Flow modeling enables you to collaboratively model, build, and test flows and their individual
components in iterations. This feature eliminates the need to create dummy rules to represent shapes
that do not exist in order to run and test flows during the development cycle.

In V5.5, this feature was enhanced to allow developers to interactively create subflow, flow action,
activity, connector, decision, and when rules during a test run of the flow.

Creating a flow model

A flow model is a new or existing flow rule placed in draft mode that may contain shapes referencing
activities, flow actions, and other rules that are not yet defined. To create a model:
 1. Place the flow rule in Draft mode by clicking the draft icon on the flow editor toolbar.
2. Working in Visio, build out the flow shell. All shapes must be connected but the rules defined
for the shapes and connectors can be blank or reference rule names that do not exist.

Best Practice: Although a shape name can be blank, it is a good practice to always name the
shape. If you name the shape here, when you configure the rule on the fly from a test run, the
rule form defaults to the shape name, and the flow will recognize it on the next test run.

3. Click Save to save the flow and validate that the flow shapes are connected and identify
incomplete shapes. Warning symbols appear on the diagram next to an incomplete shape
and on the shape's property panel next to the parameter in error. Error text is displayed on
the panel when you hover-over the symbol.

1. Run the flow model to test the flow components.

2. Repeat the process as you build out the flow until flow development is complete.

Running a flow model

Models can be run in systems where the production level is set to less than 5.

To run the model, click the Run toolbar icon ( ). As the flow runs, the user interface displays the
harness and actions for rules that exist and are complete. It overrides incomplete shapes by either
moving to the next shape or displaying a substitute action that allows you to continue processing the
flow.

The following screen shots provide a V5.5 example of a test run of a draft RequestService flow that
generates override screens where rules and/or data parameters are missing for shapes or connectors.
V5.4 displays are similar but do not include the option to create the rule from the override screen.

When the flow moves from the EnterRequest assignment shape to the CanProcess decision shape using
a single undefined connector, the flow moves to the next step in the flow and an override screen is
displayed with a Submit button. Use the Click to create link to configure the missing flow action rule.
When the flow processes the undefined CanProcess decision shape with multiple connectors, an
override screen displays a selection list of the available connecting paths and a Submit button. Use the
Click to create link to configure the missing map value rule.

When the Reject connector is selected, an override screen for the RejectService activity shape displays
with a Submit button. Use the Click to create link to configure the missing activity rule.

Understanding V4.2 advanced lock management

Summary
To prevent impairments to work object integrity, Process Commander provides a built-in work object
locking facility.

In versions prior to the V4.2SP2 (SmartBuild) release, it was possible for a business process to be
developed that would misuse this functionality, resulting in a potential data integrity exposure.

The V4.2SP2 release introduces more stringent validation at both design time and runtime that makes it
more difficult to misuse the locking facility.

Overview
A key objective of the Version 4.2 SmartBuild release is to provide automatic best practice guidance
during the development . As part of this guidance, enhancements have been made to the product that
highlight circumstances where a design or implementation falls outside of the best practices. This
article discusses the enhancements to locking that facilitate the management of work objects, and
enforce best practice for transactions.

To prevent exposures to work object integrity, Process Commander provides a built-in work object
locking facility. In releases before the V4.2SP2 release, it was possible to misuse this functionality,
resulting in a potential data integrity exposure. V4.2SP2 introduces more stringent validation at design
and runtime that makes it less easy to misuse the locking facility. This Advanced Lock Management
feature catches the following two scenarios:

Obj-Save or Obj-Delete calls which operate on an objects of a class that has locking enabled, but
which do not hold a lock, will now fail.
 Applications that lack proper error handling for these Obj-Save and Obj-Delete calls will now have
these errors flagged. Saving to the PegaRULES database will be prevented until the error is
handled.

If errors were ignored (in previous releases) it was possible to continue with the business process,
creating the possibility of saving contextually-inconsistent data. Advanced Locking keeps track of
the errors and does not let a business process Commit any data that is potentially inconsistent as a
result of the above condition.

Additional V4.2SP2 facilities provide greater visibility to lock processing:

You can trace locks with the Tracer.

A new activity makes it easier to work with locks.
A new method allows more developer control over objects waiting to be saved.

These changes affect existing applications. It is strongly recommended that you thoroughly review and
test existing applications before using them in a production environment with Version 4.2 SmartBuild
Release, as Advanced Lock Management may detect issues in currently implemented business
processes that should be addressed.

Upgrading existing applications

Beginning in Version 4.2 SmartBuild, Advanced Lock Management is enabled by default. This requires
that an object lock be held by the calling process for all Obj-Save and Obj-Delete operations on any
instances of classes which have the Allow Locking option selected.

At runtime, any Obj-Save or Obj-Delete step in an activity where a valid lock is not held on the instance
results in a step-status of FAIL. As a result of this failure, the Commit for this transaction also fails. In
addition, once such a failure has occurred, no further Commits may be executed for this user's session
(Thread),.

Follow t he following process to upgrade your applications and correct/prevent these errors:

1. Determine in which step of which activity the failure occurs.

2. If failure is due to locking, then determine the best upgrade for this particular locking requirement.

3. Upgrade the application, and test.

Determining the step where failure occurs

Users may see messages such as:

"...Commit error: A commit cannot be performed because a deferred save of an instance of class ...
failed..."

as they try to submit a work object form.

Using Tracer
In V4.2SP4, a new Tracer Event Type of Locking is available to assist in diagnosing lock events. Enable
this Event Type to track and display lock acquisitions and releases in the Tracer window when tracing a
process.

To enable this feature, on the Trace Options form, type Locking in the Event Type field, and click Add.
The Locking check box appears at the bottom of the Event Types to Trace section. Select the check
box for this option.

On the Tracer display, Event Types of Acquired Lock and Release Lock appear. Review these messages
to determine when locks are needed but not established, or when locks are released prematurely.

If locking is not enabled in the process being traced, the lack of locks and the subsequent errors are
easy to discover:

As shown above, in the

PegaSample.ShowCommitFailure activity, there is an Obj-Save in step 3 and a Commit in step 4, both of
which show a FAIL status. This identifies the steps in the activity where locking is required.
In this example activity, no lock was acquired on the instance being opened (neither the Lock field nor
the ReleaseOnCommit field were checked in the Obj-Open step), so an error will occur when the Obj-
Save step (#3) is executed.

Determining the remedy

Once a Obj-Save/Obj-Delete failure and the Commit failure have occurred, both issues must be
addressed. You must determine how best to design the locking functionality for the transactions, to
prevent locking errors (the design-time locking strategy).

In addition, you must add error handling to the Obj-Save/Obj-Delete calls, to prevent future Commit
failures while processing (the runtime locking strategy). These two strategies are described below.

Determining the locking needed - Design-time locking strategy

The purpose of locking items before making changes is to prevent data loss. Locking may be more
important in some situations than in others. For example, history or log-file entries are rarely updated
after being saved, so they may not have to be locked, as they are not transactional.

However, for work object processing, if two users have retrieved one work object from the database
(without locking it), and both make changes, then the user who saves second will overwrite the changes
made by the first user, possibly losing valuable data.

Thus, depending upon the type of processing being done, you may design different locking strategies:

Always lock
Sometimes lock
Locking not needed

These different types of locking strategies require different implementations.

Case 1: Always Lock

If application users will enter work objects for which it is important that data is not overwritten, then
locking must be enabled. For any activities that perform either an Obj-Open, Obj-Open-by-Handle, or an
Obj-Delete, the Lock parameter must be checked. As a best practice, check the ReleaseOnCommit
check box as well.

A new activity Work-.WorkLock locks a work object. Using WorkLock has advantages over Obj-Open or
Obj-Open-by-Handle. Some work objects may be opened or viewed in read-only mode (not locked, but
put on the clipboard read-only). If the user then decides to open the work object to change it, it is
inefficient to return to the PegaRULES database to re-read this object. The WorkLock activity allows the
system to simply take out a lock and open the object that is already on the clipboard.

In addition, this activity has full error handling and reporting - if another user has acquired a lock on the
object after between the time it was opened in read-only mode and the time that the user required a
lock, the system displays a "Locked by requestor XXX"S message.

In this example, the WorkLock parameters are set to show the Lock harness information. If a user tries
to open a work object upon which another user has a lock, the Lock harness appears, with information
about the user who holds the lock:

Case 2: Sometimes Lock

There may be cases where locks are sometimes needed, but not always. For example, a company may
build an application where there are many tasks which are grouped under covers. Each cover may have
multiple tasks, which can be processed simultaneously by different users. The task objects must be
locked, to prevent data from being overwritten. However, if the cover is also locked when the task is
locked, then only one user may work on a task from that cover at a time, which may not be efficient. If
the cover is not being changed with every operation, then not locking the cover will allow multiple users
to work on tasks for that cover simultaneously.

Some operations, however, will need to update the cover. For those operations, it is important that the
cover also be locked, so that data is not overwritten. Thus, the cover needs to be locked on-the-fly only
for certain operations.

The V4.2SP2 method Obj-Refresh-And-Lock handles this situation. At runtime, the, Obj-Refresh-And-
Lock method queries the database to see if any requestor holds a lock on the requested object.

If no one has the lock, then Obj-Refresh-And-Lock acquires the lock for and continues.

If the page has changed (the timestamp in the database is different than the timestamp in the
page on the clipboard), then the page on the clipboard is discarded (including any changes that
may have been made), and the page in the database is locked and then put onto the clipboard. (It
is no longer possible to make changes to a page [on a class that requires it] without a lock.)

If someone else has acquired the lock for this item, the system displays an error message: "cannot
obtain lock as Requestor xxxxx already has a lock."

Case 3: Locking Not Needed

For some classes, locking may not be needed. For example, History- instances are stored by using a
timestamp from the server clock. Each instance is therefore stored with a unique key value; these
entries are never modified after they are initially created, so there is no danger of different operators
making conflicting changes to them. In this case, the locking may be turned off for this class (in the
Class form).

Disabling advanced lock management

In unusual situations, you disable this feature. Using Advanced Lock Management is a best
practice. However, you can may choose to run in backward compatibility mode and allow
implementations that require relaxed transactional design principles.

By default, Advanced Lock Management is enabled in the pegarules.xml file in the Database node by
setting the transactionalLockManagement entry to advanced. Since this is default, the transactionalLockManagement entry
is not mentioned in the shipped pegarules.xml file.

To disable Advanced Lock Management, you must add the transactionalLockManagement element to
the database section in the pegarules.xml file, and set the value to standard :

<node name="database">
<map>
<entry key="drivers"
value="oracle.jdbc.OracleDriver;com.microsoft.jdbc.sqlserver.SQLServerDriver"/>
<entry key="storageVersion" value="5"/>
<entry key=" transactionalLockManagement" value="standard"/>
<node name="baseTable">
<map>
<entry key="name" value="pr4_base"/>
</map>
</node>
...

Adding error handling

In addition to using locking, it is a best practice to include preconditions and transitions to handle any
possible errors. At design time, locking should be implemented so that all Obj-Save and Obj-Delete
methods (for instances of classes requiring locking) will have locking enabled, preventing lock failure
errors.

At runtime, other errors may occur, such as the lock required by a particular class instance already
being taken by another user. To handle these situations, and prevent them from creating Commit
failures, error handling must be added to activity processing.

This error handling is designed to handle runtime errors only, such as the locks being in use by another
user; it will not handle situations where the lock was not taken out at all (a design error).

During processing, after an Obj-Save/Obj-Delete failure, there are three options:

Give up on the transaction - Rollback.

Retry the transaction.
Ignore the transaction failure - Obj-Save-Cancel.

In addition to these options, the application must handle messages about failures from the system.

Rollback

When a failure occurs in a deferred operation, it is important that the entire transaction be rolled
back. As an example, one transaction may take money out of a customer's checking account and
deposit it into their savings account. If the deposit into the savings account fails, the withdrawal from
the checking account must be rolled back, so the money doesn't just disappear from the account.

Every deferred operation which updates or deletes instances from the database (such as Obj-Save or
Obj-Delete) is put onto an internal deferred list, to be committed later (as opposed to the transactions
which have the Write Now parameter checked, which are committed immediately). The Rollback
method deletes the entire deferred list, thus rolling back that transaction. Most transactions use this
method of handling a run-time error.

NOTE: The Rollback method also releases any locks which were specified as ReleaseOnCommit.

When using any of the harness rules, if an error occurs, the rollback occurs automatically.
Retry the transaction

If the system reports a lock error ("lock already held by another"), then you can retry the transaction,
and allow processing to continue. For example, if the system reports that another user has the lock, the
application can present a window to the user stating something like, "This transaction was unable to
complete. Please try again," with a Submit button. If the lock were released by the other user before
the Submit was entered, then this user can acquire the lock and complete the transaction.

Make sure that your application handles situations where the second submit was still unsuccessful, and
determine how many tries are reasonable before failure and a Rollback.

Ignore failure - Obj-Save-Cancel

Important: This method is not a best practice.

Your activity can use the Obj-Save-Cancel activity method to remove one item from the deferred list.
This method will remove the failed Obj-Save from the deferred list, allowing the Commit to succeed.
This method could be used for objects where missing some data is not critical (such as log records or
history records).

Handling Messages

Process Commander offers several techniques available to handle error or failure messages,

In the following example, as part of the Rollback, the developer has determined that if the lock is not
obtained, then the activity should stop. The possibility that the lock will not be obtained is handled in
step 6, using Property-Set-Messages and the @getWorstMessage(tools) function. This function gets the
processing status error message from the system, and then Property-Set-Messages puts that error into
the specified Field . The work object form then presents this message to the user.

Next, the Transition is set to Exit the Activity.

Resolving typical problems

Commit failure
When running activities directly (rather than through a work-object form), rollback may not occur
(unless programmed into the activity). Thus, once an error occurs, no further Commits may be executed
- including the Commit that may be needed to update the activity to fix the problem. Therefore, once
the failing step in the activity is determined, you must log out and log back in, to clear the Commit error
and be able to correct and resave the activity.
Lock released by intermediate Commit prior to Obj-Save
This issue (frequently associated with Utility activities) is usually the result of unintended commits that
release a requestor's locks.

For example, as part of a work process, a second work object might be spun off from the main work
object. As part of the spinoff process, the second work object may be committed to the database. The
Commit process will commit all outstanding work to the database, so any data saved but not committed
by the main process (which is still executing) might be unintentionally committed, and the lock released
by the commit. Then when the Commit step is executed later in the main process, there is no lock
available, and an error occurs.

This issue can be diagnosed by using the new Tracer Event Type of Locking.

There are two solutions for this problem:

Remove the commit.

Reacquire locks.

Remove the Commit

If the commit is not appropriate for the (subsidiary) process in question, simply remove the commit.
Exercise caution to ensure that this commit is not from an Activity that is used in more than one place
and has other callers that rely on the commit operation.

Flow processing typically handles its own commit operations, and it is rare that you need to augment
this. Two new V4.2SP2 activities spin-off an additional work object:

Work-.AddWork
Work-.AddCoveredWork

These activities do not perform Commits. Call them for all spin-off processes, rather than the old
activities Work-.Add and Work-.AddCovered, which do contain commits.

Reacquire locks
For instances other than work objects, when an intermediate commit is required for a particular object
instance (this is rare), then reacquire locks by using either:

the Obj-Refresh-And-Lock method

The Work-WorkLock activity

Page transitions from New to Read from DB status

This issue describes a situation in which a new object instance is created and saved to the database,
and subsequent saves require the instance to be locked. The first time the instance is saved, it is new
and therefore does not require a lock (as it doesn't currently exist in the database - there is nothing to
be overwritten). Once saved, however, the instance does exist in the database, and will therefore need
a lock if subsequent saves are required.

The problem can occur when an Obj-Save for the newly-created object has Write Now checked, which
causes a commit; the actual Commit statement then requires a lock. The Write Now option is often
selected, but is not always necessary; simply uncheck the Write Now option if not needed, or
alternatively, acquire the lock prior to the Obj-Save operation.

Introducing PegaRULES Process Commander 6.2 - Process

Process flow rules are the core of BPM applications.

Here are summaries of a few of the 6.2 enhancements in this area:

6.2 offers an attractive alternative to Visio for process modeling, using notations that are based on
the Object Management Group's Business Process Modeling Notation (BPMN). The built-in Process
Modeler allows direct, graphical definition of flow elements and relationships, but doesn't require
that Microsoft Visio be installed on each developer's workstation. Process Modeler is a thin-client
editor with natural drag-and-drop operations you can use to create, arrange, and update flow
shapes and connectors. You can convert any Visio-based flow rule to use the new editor, or
continue to edit flows with Visio if preferred. Tabs on the flow form other than the Diagram tab are
the same for both types of flow editing. See:
 Introducing Process Modeler, an alternative to Visio for creating and editing flows
How to create a screen flow
Webinar Archive: Process Modeler (September 1, 2011)

Where Am I? display — The Where-Am-I? display can present both Visio-based and Process
Modeler-based flows or a flow execution that involves a mix of both editing modes. The display is
localizable.
Process Engine API — A new landing page gadget provides access to activities, flow actions and
other facilities that can be used to support flow processing without user forms, such as straight-
thru-processing.
Data Transform in connector shapes — Optionally, in a connector shape, for flows defined in
Process Modeler, you can call a Data Transform rule (formerly known as model rule) to compute
property values when that connector is followed during a runtime flow execution.
Validation rules are enhanced so that each rule can define validation based on multiple "states"
of an important property such as work item status. This approach reduces the number of validation
rules in your application. When a user completes and submits a flow action, validation of user
inputs (and other values in the work item) can be based on a proposed future work item status,
rather than the current status. If the data passes validation, the work item status changes and the
action is complete.

Assignments and Flow Actions

How to Process Select Elements from a Page Group in a
Specified Order
Summary
Elements from a Page Group can be processed in a specified order. Page Group data structures use
strings as subscript values, therefore, they are displayed in an unpredictable order. Page List data
structures, on the other hand, use integer subscript values, so ordering is possible.

To process elements of a Page Group in a specific order, you need to create a Page List data structure,
and create a reference to the properties within the Page Group.

Suggested Approach
To process select elements from a Page Group in a user-defined order:

1. If you have a Page Group already in your application, define a new Page List property in the same
 class.

Define the Page List property to be of the same class as the Page Group, and set it as a Reference
Property.

2. Create a new activity in the same class as the Page Group that will cause the Page List to
reference the value of the properties in the Page Group. List the elements in the order they should
be processed, according to the Page List subscript.

3. In the flow:
1. Add a utility shape that calls the activity you created in step 2.
2. Add a Split-For-Each shape that calls the Page List property you created.
Select the Iterate option for the Join field.

Note: If your calling flow is a screen flow, the Split-For-Each shape defaults to the Iterate and
cannot be changed.
Note: Create the flow rule that is called within the Split-ForEach shape in the Applies To class
as the Class field. The steps of this flow will be repeated for each item in the Page List.
4. Create an activity to remove the Page List, using the Property-Remove method. Add a utility shape
to the end of the flow which calls this activity.
 5. Your flow should now contain the following shapes:

Example
In this example, information about four companies is stored in a Page Group property, and elements are
displayed in the order they were created. Notice that the Customer values are not presented in
alphabetical order.

After the Page List has been populated, and the Split-For-Each shape has been reached, the elements
appear in alphabetical order. Note: This example was created using a screen flow and the standard
Work-.TreeNavigation harness to better illustrate the reordering.

Because the elements in the Page List reference the same elements as the Page Group, updates made
to the Page List are reflected in the Page Group.
How to control which of two assignments from one flow users
perform first
Summary
A developer asks: I have a flow containing a lot of assignments. For each assignment, I want a local
action that will spawn another assignment, and we don't want the first assignment finished until this
second one is completed.

Suggested Approach
There are two ways to handle this. You can either route the first assignment to a workbasket before
spawning the second assignment, or simply revise the instructions to say, "Waiting on xyz". Your
business needs will determine if the instructions-only approach is sufficient.

In either case, you need to do the following in your local action's post-processing activity:

Store the pxFlowName property from newAssignPage into an activity parameter.

Store either the pxAssignedOperatorID from newAssignPage if transferring or the pyInstructions if
changing those into an activity parameter as well.
Use the Flow-New method to start the new flow on the work object with the assignment. The
activity parameters become flow parameters in the new flow.

When the assignment is completed, it should lead to a utility shape. The utility activity, using the flow
parameters, either transfers the assignment back to the user's worklist or changes the instruction text
back as appropriate.

How to create an assignment on an embedded (interest)

page
Summary
A developer asks: When developing a flow that operates on an embedded page (interest page), how do
I create an assignment?

Suggested Approach
The primary page of Routing, Assignment, and Notify activities is the work object, while everything else
in the flow — including property references in the activity parameters —uses the primary page of the
flow.

To obtain the correct SmartPrompt for Routing, Assignment, and Notify activities, fill in the Work Class
field on the Explore tab of the Flow form.

Assume you have a flow in the work class MyWork-Approvals in which you need to gain the approvals of
every work party.

1. Use a Split-ForEach shape on the property pyWorkParty.

2. Place the approval flow in the Data-Party class named (say) PartyApproval.

3. Within that flow, add an assignment to approve something.

Perhaps you are using a special notify activity, which is located in the class MyWork-Approvals. For the
SmartPrompt in the PartyApproval flow to list this notify activity, list MyWork-Approvals in the flow rule's
Work Class field.

Remember that the primary page of all other rule references in the flow, such as a service level on the
assignment, or flow action rules, or property references in the parameters to the notify activity, are all
resolved in the Data-Party (interest page) class.

How to create flows that operate on embedded pages of a

work object
Question
A developer asks:

I've got embedded Data- class instances inside my work objects. I have some logic and flow
actions that I want to specialize for each of the subclasses on my Data- class. Are there any tricks
to writing flows that operate on embedded data classes, compared to those which operate on the
top-level work class?
In a Split-ForEach task, if I have processed enough and want to exit, how do I control that?

Suggested Approach
1. On the second tab of a Flow form, the value of the work class is indicated. It's important to specify
that correctly to get the right SmartPrompts in Visio. If you have a flow that's operating on the data
class, you define the flow rule in your data class. Flows can run on embedded pages. Set the Applies
To key part (pyClassName) of your flow to the class that it's running against, and if that's an embedded
page, then you specify that class. So you define the flow you're asking about in your Data- class.

And in your work class, if you have an embedded flow, you say it operates on the embedded page. The
Flow shape has three choices:

Current page
Embedded page
Different object.

Pick "embedded page". If you're doing a Split-ForEach, that's always on embedded Page List or Page Group.

2. Specify a When rule on the Split-ForEach properties. At runtime, the system evaluates the rule for
each embedded page. You can set a property and exit according to its value. On each iteration, the
When is iterated over, so the When rule needs to apply to the embedded page as well.

How to perform application processing after log-in with

ApplicationProfileSetup
Summary
A developer asks:

As soon as a user logs in, my application will have enough information about the user to create a
WHERE clause to be used in later invocations of our custom GetNextWork activity.

Where should I place or call the activity that creates this WHERE clause? In Data-Portal.Show?

Suggested Approach
The act of logging in causes execution of the standard activity Code-Security.ApplicationProfileSetup.

This activity —which is not marked as a final rule — provides a hook for the application to perform
whatever processing it needs. Into that activity you could call your activity that assembles the WHERE
clause you plan to use in later processing.

How to perform bulk processing for a large number of

assignments
Summary
Using the WorkManager portal, you can perform an action on multiple assignments in an application.

For example, you could accept or reject numerous purchase orders. To do this, use the bulk processing
feature.

This article shows you how to use the bulk processing feature available in the WorkManager portal.
Suggested Approach
1. In the Work Manager Portal Process Work workspace, expand My Process Actions.

2. You can perform bulk processes for the assignments on an operator worklist, or the assignments in
a workbasket. In the example, an operator has been selected from the Bulk process for pull-down
list and some purchase orders will be rejected.
3. When you select a flow action from the with action pull-down list, the list of available assignments
appears. Note that you select items in the top of the window, then select options for processing in
the bottom of the window.
4. You can expand each assignment by clicking the arrows on the left. Select some assignment to be
rejected by clicking the boxes on the left. Optionally, click the box at the top of the column in the
header to select all assignment.

5. Enter any required information for the action selected at the bottom of the window.
6. Optionally, enable Run in background to have the processing occur through the Pega-ProCom
agent.

7. Click Process Assignments.

8. When processing is complete, the window displays with checks next to those assignments that
were successfully processed (meaning rejected, in this example.)
9. If you display the worklist or workbasket of assignments again, the processed assignments no
 longer appear.
10. If you selected Run in background, you receive an email confirmation of the bulk process action
results.

How to perform bulk processing for a large number of

assignments 6.1
Summary
Using the Manager portal, you can perform an action on multiple assignments in an application.

For example, you could accept or reject numerous purchase orders. To do this, use the bulk processing
feature.

This article shows you how to use the bulk processing feature available in the 6.1 Manager portal. For
bulk processing in 5.4, see How to perform bulk processing for a large number of assignments.

Suggested Approach
1. In the Manager Portal expand Process Work on the left-hand side.

2. You can perform bulk processing of all assignments on an operator's worklist, or all assignments in
a workbasket, or selected assignments. You can apply one flow action to all the assignments, or to
only those assignments of a specific work type.

For example, if a manager needs to use the Reject flow action to reject assignments of all work
types, select the operator ( from the Bulk process for pull-down list. At the on work type pull-
down select All Work types. At the with action pull-down list, select Reject.
 3. When you select a flow action from the with action pull-down list, the list of available assignments
appears. Select items in the top of the window, then select options for processing in the bottom of
the window.

4. Expand each assignment by clicking the arrows on the left. Select the individual assignments to be
rejected by clicking the checkboxes on the left. Optionally, click the box at the top of the column in
the header to select all assignments.

5. Enter any required information for the action selected at the bottom of the window.

6. Optionally, select the Run in background checkbox to have the processing occur through the Pega-
ProCom agent.

7. Click Process Assignments.

8. When processing is complete, the window displays with checks next to those assignments that
were successfully processed (assignments saved, in this example.)

9. If you display the worklist or workbasket of assignments again, the processed assignments no
longer appear.

10. If you selected Run in background, the Pega-ProCom agent sends to you an email confirmation of
the bulk process action results.

Additional Bulk Processing Options

To bulk process assignments by Work Type

1. In the upper left area of the Manager portal, select the work pool name that contains the
assignments to be processed. Locate the row containing the label Bulk Process by Work Type.

2. Select one Work Type from the drop-down list. At the Bulk Processing screen, at the Create
Operator field enter the first two letters of the Operator's name to view a list of results. Select an
operator's name from the Create Operator list.

3. Enter the first two letters of the Operator's name at the Update Operator field to get a list of
results. Select an update operator from the Update Operator list. Note that the operator fields use
operator names and no ID's.

4. Select a status from the Status list, for example Resolved–Completed.

5. Select the Created After and Updated After dates. Click Update Filter to return search results.

6. Results are listed below. Click the checkbox to select a specific result, or click the checkbox in the
header to Select All. Click on any of the tabs to sort by ID, Subject, Status, Update Operator, or
Update Time.

To bulk process assignments by Cover:

1. In the upper left area of the Manager portal, select the work pool name that contains the
assignments to be processed. Locate the row containing the label Bulk process cover.

2. Select one Cover from the drop-down list, for example Build a Product.

3. Enter the first two letters of the Cover ID to view a list of results. Then Select a cover ID from the
Cover ID list. Click Process Cover. All Work Objects in a Cover are displayed in the Bulk Processing
screen.

To bulk process assignments by Folder:

1. In the upper left area of the Manager portal, select the work pool name that contains the
assignments to be processed. Locate the row containing the label Bulk process folder.

2. Select Process Folder. Enter the first two letters of the Folder ID to get a list of results. Then Select
a folder ID from the Folder ID list.

3. Click Process Folder. Results are displayed in the Bulk Processing screen.

How to recall an assignment using the Split/Join shape

How to recall an assignment using the Split/Join shape
Summary
A developer asks: If I drop an envelope into an official USPS mailbox, I can't get it back. Only the USPS
staff can get it and process it. If I drop an envelope into my personal mailbox, I can remove it at any
time until my mailman removes it. (If anyone else removes it, that's a federal crime.)

Can Process Commander offer capabilities similar to the personal mailbox? Once I perform an
assignment that normally advances the flow to assign work to another operator (whose worklist I cannot
see), is there a way for me to "recall" that assignment, perhaps to update it further and then reassign
later?

Suggested Approach
Use a Split/Join flow shape in the flow to achieve this.

1. Set the Join When to a value of ANY .

2. Route one connector to an assignment to the next assignee, and the other to your own worklist.
3. The flow then splits and creates two assignments, one for each of you.

If you perform your assignment first, the second assignment for the other assignee is automatically
deleted. If the other assignee performs his or her assignment first, the one for you is automatically
deleted.

This also works for another business setting, where you are a bidder and the other assignee has
something for sale. You can revise your bid as often as you want, up until the seller accepts it.

How to route an initial screen flow to a workbasket

Summary
As an application developer, you have a work object that goes to a screen flow where application users
can specify information in one or more screen forms. You want to route the work to a specific
workbasket so that the work object is in the workbasket initially when it reaches the screen flow. (See
the example scenario.)

However, by default, PRPC will always prevent this because the router logic assumes that work in a
screen flow must first be processed by a single user (an Operator ID); therefore, the default behavior
always routes work in screen flows initially to user worklists. You can work around the default behavior
and assign a screen flow initially to a workbasket by following the Suggested Approach.

Example Scenario
1. Create a screen flow with more than one assignment.
2. Add routing logic in the Start shape of the screen flow.
3. Label the Router activity as "ToWorkbasket" and specify the workbasket from the selection list.
4. Create a process flow with one assignment after the Start shape and one flow action on it.
5. Connect the screen flow created in Step 1 to the flow action. This is the main flow that you want to
create the work object.
6. Connect the flow End shape to the screen flow.
7. Run the main flow to test it.
8. At the first assignment, complete the fields of the work form displayed by the flow action and click
Submit.
9. See this error on the screen:
Flow <<em>name of Screen Flow</em>> had an error in step AssignmentSF4:
Unable to open assignee's Data-Admin-Operator-ID record <<em>Operator ID</em>>

Suggested Approach
Choose one of the following approaches.

Insert an assignment shape in the main flow to route it to the workbasket before the screen flow
 subprocess. Then the application user can see and use the screen flow after he or she pulls the
work from the workbasket.

This approach creates an additional screen for the user to submit before entering the screen flow. If this
is not desirable, choose the second approach.

Avoid the extra screen created in the first approach: Create a flow action that performs
AutoSubmit when the user opens the assignment.

1. Create a new flow action, for example, StartScreenFlowAuto.

2. On the HTML tab, in the HTML Generation dropdown list, select Reference HTML.
3. In the HTML Reference field, specify the standard HTML ActionAutoSubmit.
If the new flow action is the default (highest likelihood) or is the only available flow action from the
assignment, then as soon as the user opens the assignment from the workbasket, it will proceed to the
screen flow.

Additional Information
How to create a screen flow

Flow form, Editing in Visio - Creating and editing screen flows

Flow form, Editing in Process Modeler - Creating and editing screen flows

Router activity - definition

Related GCS Case Object Number

KR-1062, SR-93487, BUG-137164

How to route assignments evenly among the operators in a

work group
Summary
The standard function pickLoadBalancedWorkGroup() employs the following algorithm:

1. Get a list of all operators in a work group.

2. For each operator:

If Operator has Skills and Is Available,

get all assignments assigned to user,

calculate a "total urgency."

3. Return the operator who has the lowest total urgency.

This approach can impact performance. With many operators, this function can execute many SQL
SELECT operations on the assignment table.

A developer asks: Our requirements are simpler than what this load balancing algorithm seems to offer.
We want to identify the available operator who has the fewest assignments — the shortest worklist. .

We're thinking of building a custom SQL query that joins the assignment and operator tables. Is that a
good approach?

Suggested Approach
The load balancing approach in the standard function may be more than you need.

In your case a more efficient way may be a custom SQL query that joins the count of assignments from
the assignment table with the operator table, ordering the operator table by the number of
assignments.

As you experiment with this approach, be sure to test what you build by checking the Performance tool
statistics, checking the load on the database, running some volume testing, and so on.

If your approach appears to be running well, such testing and analysis will show whether your
implementation is actually performing as well as you require.

How to save each step of a screen flow execution

Summary
A developer asks: Are work objects saved in the PegaRULES database while screen flows are in use?

For example, can I complete the first few steps, log off, then return later and complete the remaining
steps?

Suggested Approach
By default, screen flow steps are not saved to the PegaRULES database.

However, you can set an attribute (in the Start shape) when editing the flow rule that causes a
database save after each step in a screen flow.

You should turn this on as appropriate, but only where supporting such interim step saves are
necessary, as the database save operations add to processing workload.

Note that this approach causes each step to be treated as an assignment, which means that a line is
added to the work object history for each step.

Techniques for clearing stale data from the pyWorkPage

page
Summary
A developer asks: Are there any best practices or guidelines for cleaning stale data from the pyWorkPage
page or building "undo" capabilities?

We have a class with many properties that are relevant only based on other properties. The user
interface is a series of forms that branch depending on input data and fill in only the relevant properties.

However, application users want to jump back several steps to review and possibly change what they
entered. Based on their changed inputs, flow execution will branch to different forms and fill in new
properties.

Issue: The property values entered previously may no longer be valid. Validation and declarative rules
then produce undesired behavior, because the clipboard still holds stale property values.

Is there any guidance / advice available regarding:

Techniques to clean the clipboard.

Techniques to create save-points and snapshots of pyWorkPage.
Best practice for validation and declarative rules given the possibility of stale properties on
clipboard?
Suggested Approach
The following approaches have been used effectively to clear data or go back in such situations:

At certain points, provide a flow action that takes users back to an earlier point in the processing.
Along the path back, invoke an activity that clears out the properties to be to reset or which could
negatively affect validation and or declarative rules.

Provide a local action that allows users to choose a value different from the current value. In such
a scenario, create a "clear-properties" activity that takes a parameter. Invoke that activity as the
flow action's "Before this Action. .." activity -- to force the clearing out of old values.

Use pickBalancedOperator() in routing activities to fine-tune

operator workloads
Summary
Routing assignments to the "best" operator is crucial in achieving good staff utilization and high
throughput. In addition to considering required and desired skill levels, routing may also depend on how
much work already is assigned to the candidate operators, how much of their workload is already past a
goal deadline, planned absences such as vacations, and other factors.

A function rule, pickBalancedOperator(), in the Routing library allows a routing activity to select an
operator (from those who belong to a specific work group) based on desired skills, required, skills, and
three other parameters.

The standard routing activities use this function rule. If desired, your application can call this function
using different parameters to factor in the size of each operator's current workload, whether they have
assignments that are past service level goals or deadlines, and assignment urgency or another numeric
property. Call pickBalancedOperator directly if you want to change how these factors are weighted.

The function uses advanced database retrieval techniques to achieve high performance. The function
returns a randomized list of the qualified operators if there is a tie. Usually (especially if worklists are
taken into account) the result is deterministic. If there are two users with the exact same workload and
the parameters are just right, it will randomly select one.

Standard Routing Activities

Work–.ToSkilledGroup
Using skill–based routing the assignment is routed to an operator in the work group who has the
requisite skills and possibly the desired skills. If none meet all the criteria, assignment is routed to the
work group manager. This activity considers the routing characteristics of Availability, required skills
and desired skills.

The Work–.ToSkilledGroup routing activity sends an assignment to a randomly selected operator within
a specific work groupwho:

1. Is available between the time the assignment starts and the time it is due

AND
2. Has the minimum skill proficiencies to complete the assignment

Work–.ToSkilledGroup uses the skill table pr_index_operatorskillsto search for an operator with sufficient
skill levels using the database side to minimize performance impact.

Work–.ToLeveledGroup
The Work–.ToLeveledGroup routing activity is similar to Work–.ToSkilledGroup except that it sends an
assignment to the operator within a specific work group while taking operator workload into account
and assigns work to the least busy operator who has the required skills.

Suggested Approach
Skill-based routing using Work–.ToSkilledGroup

To use skill-based routing in a flow, complete the following steps:

 1. Add a Router to the Assignment shape that requires a skilled member of a work group.

2. In Router properties, Add the Name and Activity rule.

Add the work group of the Operators you wish to include. Add the Skills and Skill Levels desired
(Skill levels range from 0 to 9 typically). In this case, German Skill Levels of 9 are desired and
French Skill Levels of 8 are Required.

3. Open the Activity rule routing the assignment ToSkilledGroup.

4. Return to your flow and save any changes. The assignment will be routed to the Operator who is
available, has the appropriate skills (in this case, German Level 9 and French Level 8), and has the
least workload in the designated group.

In this example, there are three Operators in the workgroup [email protected] who meet the
prerequisite skills— [email protected], [email protected], and [email protected]—
possess the necessary language skills.

Smith is strongest in German.

Jones has German and French skills similar to Smith.

Ramirez knows Russian.

Of all the Operators in the [email protected] work group, [email protected] has the
appropriate levels of both German and French to complete the Assignment. The Assignment is therefore
routed to [email protected] for completion.

Skill-based routing using pickBalancedOperator()

1. Save the Activity Work–.ToSkilledGroup into your ruleset. Expand row # 1. PropertiesValue is set to
pickBalancedOperator.

2. The routing function pickBalancedOperator accepts several parameters (viewable by clicking the
Parameters tab). pickBalancedOperator picks the operator who is available, has the appropriate
skills, and has the least load in the WorkGroup. The above values, 0, 0, 0 have not been set, and
therefore pickBalancedOperator will not take workload into account when routing. See below on
how to add these values.
 3. To customize pickBalancedOperator, modify the following Parameters with a value of 1 — 10 in
your saved version of Work–.ToSkilledGroup:
pastGoalMultiplier ⁄ pastGoalDeadlineMultiplier– determine the workload of the user.
desiredSkillMultiplier – determines how important it is to assign the work to a user with
the desired skill.

The desired skill multiplier determines how important it is to assign the work to a user with the
desired skill. For example, if user A has a huge workload and the desired skill for an assignment
and user B has nothing in their worklist (but no desired skill), who should the assignment go to?
The formula is: if there are 5 desired skills and the multiplier is 10; any user who possesses the
desired skills has their effective total workload reduced by the number of desired skills they
possess * the desired skill multiplier.

The above values - 1, 2, and 4 correspond to pastGoalMultiplier, pastGoalDeadlineMultiplier, and

desiredSkillMultiplier respectively.

When and how to set up "back-to-back" assignments

Summary
Process Commander provides process management and automation through six functional capabilities
(the Six R's), one of which is routing. Automated routing uses characteristics of work, together with
workforce knowledge to make intelligent matches and assignments.

One way your application can influence routing is with a back-to-back assignment. The informal term
back-to-back assignments describes the case when a user who completes an assignment for a specific
work object is then able to work on a second assignment for the same work object. The second
assignment may arise from the same flow execution or — in unusual situations — a different unrelated
flow execution.

When appropriate and feasible, back-to-back assignments are likely to improve user productivity
because recent exposure to the work object, its parties, and attachments makes coming up to speed
quicker. Your settings on the Action tab of the Flow Action form can increase the likelihood that
assignments will be performed back-to-back when possible.

Each time a user completes an assignment, your application can select and provide another assignment
for that user to work on next. By choosing the best, most appropriate assignment to work on next, your
application can promote user productivity, timeliness of processing, and customer satisfaction.

The following example flow requires a user to gather pharmacy information from a patient over the
phone and enter the information into the application. Once this information is submitted, the Call
Pharmacy assignment requires the user call the pharmacy to refill the patient's prescription. Since the
user gathered the pharmacy information in the Obtain Pharmacy Information assignment, it is
productive to have that user complete the Call Pharmacy assignment too.

Suggested Approach
To edit a flow action to enable back-to-back assignments:

1. Open the flow action rule for the flow action that, when chosen, is to redisplay the Perform harness
again with the second assignment.
2. From the Actions tab locate the After This Action section which defines processing that is to occur
after the user submits the action form.

3. Check the Look for an assignment to perform? checkbox .

This checkbox causes your application to search for another assignment for the same work object
(and same flow execution) on the user's worklist. This feature is called back-to-back assignment
processing.

As a best practice, select the Look for an assignment to perform? checkbox. In many situations,
two or more assignments may be open for one work object, assigned to the same person. When a
 user who performs one of these assignments is also qualified to perform other assignments, it is
usually most efficient to have that user perform the assignments one after another, because the
work object is familiar.

The system only finds and presents assignments that the current user is qualified to perform and
that are available to be completed (that is, those forwhich the value of Assign-.pyActionTime is
past). The action time is only set when there is a service level specified for the assignment,
otherwise the action time is considered now.
For example, an assignment instructs a user to "Record the closing stock price". This assignment
can only be completed after 4 PM, when the market closes. If the assignment is created at 2 P.M.,
the action time is in the future. As a result, the system displays the Confirmation harness instead of
the Perform harness.

4. Once the Look for an assignment to perform? checkbox is selected three additional checkboxes
appear:

Checkbox Description

If not found, look in

Select to cause Process Commander to search for open assignments on this
other flows on this
user's worklist from other flow executions active for the same work object.
work object?
If not found, look in Select to cause Process Commander to include, when searching for back-to-
flows on the cover back assignments, open assignments for the cover work object to which this
object? work object belongs.
For each also consider
Select to include assignments in workbaskets in the search for back-to-back
assignments in
assignment processing.
workbasket?

If... Then...

when that assignment is completed (using that flow action) and the flow leads
to another assignment (in the same flow or a subflow called by that flow), the
you select only the user sees the Perform harness displaying the default flow action for this new
Look for an assignment assignment, given that:
to perform? checkbox
the current user is the assigned operator
and
the assignment's action time is now or earlier.

you select the If not at runtime, after checking if a new assignment meets the above conditions and
found, look in other finding that it does not, Process Commander also checks if there are any other
flows on this work flows on the work object that have assignments assigned to the current
object? checkbox operator and that have reached their respective action times.
you select If not found, after exhausting all assignments on the work object, Process Commander
look in flows on the examines the cover object (if any) for assignments assigned to the current
cover object? checkbox operator and that have reached their action time.
you select the you
the search scope expands to examine the assignments in the workbaskets
select For each also
associated with the user's work group (through the Work Group field on the
consider assignments
Workbasket tab of the Workbasket form), as well as assignments on the user's
in workbasket?
worklist.
checkbox

Why don’t pre-processing activities, circumstanced flows,

and assignments on embedded pages work with Bulk
Processing?
Question
A manager asks: I am using the Bulk Processing features to process several assignments with a flow
action.

This flow action references both a pre-processing activity and a post-processing activity. Only the post-
processing activity of the flow action is called.

Why doesn’t the pre-processing activity of the flow action run?

Answer
Bulk processing does not open the work object when the flow action is displayed. Therefore, you should
not specify pre-processing activities in a flow action if you intend to use it with Bulk Processing.

Understand that Bulk Processing is also not intended for use with the following:

Circumstanced flows
Assignments on embedded pages

Like pre-processing activities, circumstanced flows cannot be bulk processed because the work object is
not opened when the flow action is displayed.

Related Topic
How to perform bulk processing for a large number of assignments

Related GCS Case Object Number

KR-3

Understanding the pyWorkPage and Spin-off tasks in flows

Summary
A developer asks: I'm trying to manipulate two work objects within a flow. My first flow needs to open a
second work object, and spin off a flow on this work object before continuing on the current flow.:

At what points in work object processing does the work object need to be named pyWorkPage?
At what points in work object processing does Process Commander rename my current work object
to the name pyWorkPage?

Suggested Approach
Here are some best practice, guardrail-aware observations.

pyWorkPage is a reserved page name. It is true that you would collide with it when you rename an object
to pyWorkPage. But other than that fact, you should ideally be oblivious to the fact that it even exists as a
name.

A key question is: when does your service processing end, and flow processing start? If you don't
manage those points, then your application can experience problems resulting from intertwining your
service processing with flow processing - and not only page name problems, but also transaction
integrity problems.

For the most part, you want to create a new work object and get into the flow as soon as you can. And if
you need to create multiple work objects, for example need to create a second work object while you're
already working on one in a flow, then your utility should not be concerned with pyWorkPage, but should
be completely independent —saving its objects using whatever page names it needs, and then finishing,
getting out of the picture, and letting flow processing take over.

The key challenge in designing an application with multiple work objects is how to do your non-flow
processing piecemeal or atomically, then get out of the way and return to flow processing to let flow
processing coordinate the multiple work objects. There aren't any points in work object processing
where you need explicitly to name your Page-New objects that are created by services pyWorkPage.
Also: If you do have multiple work objects and they participate in the same flow, then you must be
careful about locking and ensuring to make things part of the same transaction. See locking details in
Understanding V4.2 advanced lock management.

Related topics

Understanding V4.2 advanced lock management

Additional Flow Shapes

How to advance to one of multiple first tasks in a flow rule
Summary
A developer asks: I have a flow that has a several starting points.

If I use an activity and the Flow-New method to start the flow execution, then in the next activity step
set a ticket to get to the flow shape that I want processing to start, Process Commander still executes
the initial tasks in the flow.

How can I avoid this?

Suggested Approach
Don't use tickets.

Make the first shape in a decision shape that determines which shape to advance to next.

This allows the flow diagram to be easily understood.

How to automatically create a new work object and transfer

it to a subflow
Summary

Your process may have a flow that creates a work object, does some processing against that object,
and then creates a new object that is processed in a subflow. When the subflow completes, the new
work object is resolved and control returns to the calling flow where the original work object resumes
processing. This process can also be used when working in a cover flow, which creates a covered object
for the subflow.

You can automate the process using an activity in the top-level flow that creates a new work object and
calls the subflow. This configuration can provide the work user with a smoother transition between
steps during a work session. For example, the user can work on the first item and then go immediately
to work on the new one without having to step through an Add Work flow action.

This article shows you how to create this configuration using flows within the same Work class.

Suggested Approach
In this example, you create the following:

A top-level flow
An activity that creates a new page, adds work to it, and transfers it for execution.
A subflow where the new work is executed.

Build the example as described in the following steps.

1. Create a flow called WorkOES in a work class (AlphaCorp-OrderEntrySystem in this example) and
add the shapes as shown here:
 Do not enter the shape properties for the Utility and the Flow (subflow named BetaWorkOES)
shapes yet. An assignment shape is included so that the you can examine the object and the locks
on the clipboard before the object jumps to the second flow.
2. Create a flow called BetaWorkOES in the same work class. For testing purposes, this flow is simple
and needs only to have an assignment shape so that you can examine the clipboard and locks
when you run the flow.
3. Create a new activity called AddOESWork. The Utility shape in the main flow uses this activity to
create a new page, add work to it, and change the flow name.
4. On the Pages & Classes tab on the Activity form, enter pyTempWorkPage as the page name in your
work class.

5. On the Steps tab, create the steps as shown below. All use the same step page
(pyTempWorkPage).

Step 1: Enter method Page-New — Use the pyDefault model and your work class.
Step 2: Enter method Property-Set — Set .pyFlowName to double quotes ("").
Step 3: Enter method Call and standard activity AddWork (if the calling flow is a cover flow, use
AddCoveredWork instead).
Step 4: Enter method Property-Set — Set .pyFlowName to the name of the second flow,
"BetaOESWork."
After you have created the activity, do the following in the OESWork flow:

1. Select the Utility shape. In the Utility Properties panel, select AddOESWork in the Rule field and
click Apply.

2. Select the SubProcess shape and enter the information in the SubProcess Properties panel as
shown here:

Set Define Flow to On Another Work Item, select your work class, enter the page name
"pyTempWorkPage", set Flow Rule to BetaWorkOES, and click Apply.
3. Save the rule.
4. Start the WorkOES flow to test the configuration. Note the work object ID when the object is
created at the first assignment. When the object reaches the assignment shape on the second flow,
verify that the work object id has changed. For example, when you create a work object in
WorkOES, it appears as a new object in your worklist (for instance, W-21) and is locked, which you
can verify using View > System > Locks > My Locks. When you approve the work, a new object
starts in BetaWorkOES and the object ID changes to W-22. This object appears in the worklist and
is locked. W-21 should not appear either in the worklist or in the list of locked objects.

When W-22 is approved or rejected, W-21 resumes in the Review Work assignment in WorkOES.

How to control history instances written to the audit trail

Summary
You can control the work object history written to the audit trail using the system settings rule Pega-
ProCom.FilterHistory and a copy of the standard decision tree rule Work-.FilterHistory. You can write all,
some, or no records according to your system's production level. Controlling history writes allows you to
limit the types of audit lines that end users can view in the audit trail. In addition, you can improve
system performance by reducing the number of unnecessary history writes to the pc_history_work table.

This article explains how you create and modify these rules to control history write behavior.

Note: This feature does not apply to user-created history instances used in an Audit Note field or in a
History-Add method.

Suggested Approach
To modify the default behavior, do the following:

1. In the Rules by Type Explorer navigate to SysAdmin>System Settings and open the rule
instance Pega-ProCom.FilterHistoryas shown here:

Create an instance in your application RuleSet. Do not change the Owning RuleSet (

Pega-ProCom

) and Setting Purpose (FilterHistory) key values.

This array contains five rows for production levels 1 (experimental) through 5 (production) and
correspond to the production level in the system data instance in class Data-Admin-System . The default
values used in the .FilterHistory rule are as follows:

WRITE_ALL — all work history is written.

WRITE_SOME — checks the FilterHistory decision tree (see below) to determine whether to write
a specific work object history instance. By default, all history instances are allowed and are
written.
WRITE_NONE — all Pega-ProCom-written history is skipped. Custom history instances used with
the History-Add method or in an Audit Note field are not affected by this rule.

For example, if your system is at production level 3, the default system settings rule .FilterHistory allows
all history records to be written. If you want to filter the history records, change the value in row 3 to
WRITE_SOME. The system settings rule will then use the decision tree rule .FilterHistory to determine
which records are written.

After you have made your edits, save the rule and run the History-Work-.resetFilterHistory activity
to make the changes effective. Alternatively, restart the server.

Filtering history instances

1. To filter the history records used by the WRITE_SOMEvalue in the FilterHistory rule, open the
FilterHistory decision tree rule in class Work- as shown here:
 2. Create an instance in your application RuleSet.Change the Applies To class to the class group of
your application. Do not change the Decision Tree key value (FilterHistory). The tree contains a list
of parameters that evaluate every field value rule for .pyHistoryMemo in class Work- , all of which
return "true" by default. This means that all history records for all fields in the tree are written.
3. Change the return value to "false" for the field values you do not want written to history. For
example, when an item is saved or an item is created, a record is written for each of these actions
and appear in the audit trail. If you do not want to write "ItemSaved", change its return value to
"false".

To optimize performance, it is a best practice to sort the most commonly used values by
frequency; that is, put the fields you use most at the top of the tree.

4. Save the rule.

5. Note: Changes to these rules take effect going forward only. History instances already written
remain in the audit trail.

How to create a custom Smart Shape

Smart Shapes allow you to easily add frequently-used utilities to your process designs. Available on the
Process Modeler Smart Shape palette, the standard utility Smart Shapes can be used in process flows
with little to no additional configuration.

You can also take advantage of Smart Shape capabilities by designing your own shapes based on PRPC
standard activity APIs. This article describes how to create your own Smart Shape and add it to the
palette.

Example
In a student loan application, you can design a Smart Shape that automatically adds a history memo
indicating that an applicant has finished the student loan application process after the Education Details
flow action is complete.

Use the standard AddHistory activity as the basis for creating a new Add History Smart Shape:
Use the Smart Shape in your process to add the history memo:

Basic steps
To create the Smart Shape:

1. Copy the AddHistory activity to your application.

2. Create a post processing data transform that maps the property in the Smart Shape's flow action
to the activity's parameter.
3. Create a flow action (and its section) that captures the required parameters and displays them in
the user form.
4. Specialize a navigation record that displays the Smart Shape on the palette and defines the user
interaction.

Step 1: Copy the AddHistory activity to your application

1. Open the APIs landing page by selecting Designer Studio > Processes & Rules > Processes > APIs
2. Click the AddHistory link to open the AddHistory activity.

3. Save the activity to your application.

Step 2: Create a data transform

1. Before creating the data transform, create a text property named .AddHistory in your application.
On the General tab, specify pxTextArea in the Display and Validation area's UI Control field.
2. Create a data transform named AddHistory in your application.
3. On the first row, enter the following:
Set in the Action field.
param.HistoryMemo in the Target field. This is the HistoryMemo method parameter used by
the AddHistory activity.
. AddHistory in the Source field. This is the property you created and used by the parameter.

4. Save the data transform.

Step 3: Create a section and flow action

Create a section
 1. Create a section named AddHistory in your application.
2. Drag and drop the Text Area control from the Basic palette onto the layout.

3. Open the the control's Cell Properties panel and enter:

.AddHistory in the Property field.
History Memo in the Label field.

4. Save the section.

Create the flow action

1. Create a flow action named AddHistory in your application.

2. On the Layout tab, enter AddHistory in the Section field.

3. On the Action tab, enter AddHistory in the Data Transform field.

 4. Save the flow action.
5. Open the AddHistory activity.
6. On the Parameters tab, enter AddHistory in the Local Action for Parameter Display field.

7. Save the activity.

Step 4: Create the navigation record

1. Open the navigation record .pyExtendedAPIs and save it to your application.
2. On the Editor tab, double-click the first row to open the configuration dialog.
3. Select Selected Item in the Type field, and enter Add History in the Label field.

4. Add a row on the dialog's Action tab. The behavior dialog displays.
5. In the Action section, click the Select link and select Other > Run Script.
 The Behavior dialog refreshes and displays the Run Script options.
6. Enter:​
addApi in the Function Name field.​
Utility and AddHistory in the Parameters fields.

7. Click OK to exit the dialog.

8. Click the add row icon to add another action.
9. Select the Run Script action.
10. In the Function Name field, enter "ViewerManager.executeAction" (include quotes).
11. In the Parameters field, enter this value:
script:{name:\\u0022addNode\\u0022,type:\\u0022Utility\\u0022,args:{apiName:\\u0022AddHistory\\u0022}}
12. Click OK to exit the dialog.
13. Open the Options tab on the configuration dialog and enter pzAPIUpdateCaseIcon in the Icon Class
field. This class is defined in the standard Styles for Editor (pyMxGraphViewerStyleDefault.css) text
file.

14. Open the Advanced tab on the configuration dialog. In the Show area's When field, remove the
default never value and replace it with Always.

15. Click OK to close the dialog.

16. Save the navigation record.
Test the Smart Shape
1. Select the case type in the Cases Explorer.
2. On the Case Designer's Stages & Processes tab, open the Process Outline of the Stage that
contains the process you want to modify (click the Configure Process Details link under the last
step beneath the Stage shape).
3. In the outline tree, select the flow to display it in Process Modeler.
4. On the toolbar, click to open the Flow Shape palette.
5. Select Smart Shapes > Add History.

The Smart Shape displays on the layout.

6. Position the shape between the Details assignment and End shapes.

7. Click the Adds history to case shape to open its properties panel.
8. Enter the memo that displays in the case history after the Education Details action is processed.

9. Start the process.

10. When the EducationDetails assignments is complete, open the History tab on the work form. The
memo you entered in the Add history to case Smart Shape displays, as shown below:

How to develop a model rule for a work type

Summary
When an application overrides the Work- pyDefault model, which properties are most often set to
application-specific values?

Suggested Approach
When you create the pyDefault model in your application's Work- class, you do not need to repeat many
of the settings in the Work- pyDefault model, because to the Call Super Class Model check box causes
that model to execute first.

The following properties are typically overridden, however:

.pxUrgencyWorkClass — Specify how much urgency the work object starts with. For example, if
your application has two work classes, Enhancement and Bug, you may want work objects of the
Bug type to have a higher starting urgency.

.pyFlowName — (V3.2 and earlier) Set this in your model to identify the primary flow for this work
class. The primary flow is the one that is started on the work object when it is created.

.pySLAName — Specify a service level for the work object (as opposed to a service level for one
assignment) that monitors processing until the work object's status changes to "Resolved-xxx".
(Examine the standard service level rule Work-.OverallSLA for an example.) If you don't need this
capability, set this property value to "".

.pyWorkIDPrefix — Determine the prefix your work object IDs start with. For instance, the IDs of
work objects of the Enhancements work type could start with E- while IDs for Bugs start with B-.

.pyWorkIDSuffix — (Optional) This property causes the generated IDs to end in a specific suffix.

.pyStatusWork— The Work- pyDefault model sets the initial work status to "New". You may desire
something else, such as "Open" or "Pending-Qualification". Remember that pyStatusWork values
are enumerated as field value rules. If your application requires custom work statuses, you must
create a field value rule for each.

.pyStatusCustomerSat — Much like .pyStatusWork, the values for the customer satisfaction
property are enumerated as field value rules. The Work- pyDefault model also defaults this to
"New".

.pyConfirmationNote — Determine the text to appear on the Confirm harness after the work object
form is submitted. The Work- pyDefault model defaults this to "Thank you for your input".

.pyNotifyQuickStream — The flow action Work-.NotifyQuick uses the value of this property to
determine which correspondence to send. This is set to QuestionAboutItem in the Work- pyDefault
model.

How to execute a map value rule within a flow

Summary
A developer asks:
I have a map value rule that translates an errorCode to return an errorMessage. This rule is tested and
working. So in a flow, I want to have an ALWAYS connector emanating from the diamond Decision shape.

However, the Decision shape does not support an ALWAYS connector.

Is there a way to represent this in a flow without wrapping the map value inside of an activity?

Suggested Approach
The decision flow shape is not really the right mechanism to use just to translate a value, because it
creates two or more outgoing connectors defining branch options based on the value.

Instead, use a Utility shape to execute a one-step activity that simply calls the Property-Map-Value
method.

How to save a work object that fails validation

Summary
A developer asks: I have an activity that is invoked by a service. In the service activity, I create a work
page, and start a flow execution. In the flow, I use a utility activity to assign values to work object
properties.

At the end of this utility, I want to know that the work object will save successfully before moving on to
subsequent steps. If it won't save, then I'd like to somehow still save this work object data so that I can
later examine it to see what went wrong.

Are these steps the recommended implementation?

1. Use Page-Validate to test to see if the object will save successfully.

2. If stepStatusGood, exit the Utility.
3. If bad, do an Obj-Save (deferred, with the With errors parameter left unchecked)
4. Taskstatus-Set to return a Fail to the flow
5. exit the Utility.

The flow execution continues (quickly reaching an EndFlow shape, which returns control to my
initial activity). The initial activity then performs a Commit method and finally sends a service
response.

Suggested Approach
The work object database table is not a natural or recommended place to log errors. If the
reason you wish to persist the work object — despite errors — is simply to collect forensic
evidence on the nature of its errors, consider the following alternative:

Use a separate Data- class (not the work object class), into instances of which you persist the
XML string of the data coming in from the service and a snapshot of the XML and its
generated page.

That way you'll have all the information in a format that can be digested in a lot of different
ways, in a place where saving it with errors is not an issue.

For work pages with errors, return to the service the name of the Data- class in which
you're capturing the forensic evidence, and the ID of the instance.
For work objects without errors, return to the service the class and the work object ID.

If you receive errors upon subsequent service manipulations of already persisted work
objects, you can use the same data class to persist the forensic evidence, and in addition
capture in that instance an image of the work object page in XML format.

Alternatively, you could place the forensic evidence into an embedded page for which the Do
not validate embedded pages field (on the Property rule form ) is specified, and then you
 could save that flawed page without actually validating it.

How to set a maximum loop count in flows

Summary
Business users appreciate Process Commander's approach of displaying the business process as
configurable shapes in a process flow. However, many business users expect the high-level process,
including loops, to be visible as flow shapes.

Looping is sometimes accomplished by iterating through items in an activity. Although that’s effective,
many business users prefer the loop logic not be “hidden” in the activity. Similarly, placing the loop in a
subflow appears to “hide” the nature of the loop from the business users as well. By contrast, flow rules
are very visual and open.

Placing a loop inside of a flow can, however, result in a loop count error at runtime:

This flow has looped back to this shape too many times - it may be in an infinite loop.

Flow execution halts.

For most Process Commander versions, you can change settings to increase the tolerance for infinite
loop executions. Details depend on your version.

Suggested Approach
The image below depicts an example of a loop that might be required in a flow rule. In the example,
batches are retrieved for all items in Get Contract Batch shape. When the last batch retrieval attempt
produces no items, the ContractExists? shape determines that loop is finished. The loop is incremented
in the Is It New Batch shape.
Practical considerations when designing a loop inside of a Flow Rule

Flow looping before v5.2

In releases prior to v5.2, the infinite loop threshold setting is in the FlowFUA library. The
MaxFlowLoopCount is defaulted to 25

You can change this to a higher or lower value. Then regenerate the library to have this change take
effect.

Flow looping in v5.2, v5.3, v5.4

In V5.2, V5.3 and V5.3SP1, the FlowFUA library is marked as Final. Looping through activities and
subflows is the only recourse.

Beginning in v5.3SP2, and continuing in v5.4, a new Rule-System-Setting named MaxFlowLoopCount is

available, permitting changes to this important loop threshold constant.

In V5.4, the default value is increased to 500.

How to simplify a flow diagram that has many similar

workbaskets
Summary
A developer asks: I have three workbaskets, with each assigned to a different group of people. Each of
these has a different primary connector flow action, and three flow actions that they share in common.

This makes the flow diagram look very busy. Are there techniques that I can try to simplify the
appearance?

Suggested Approach
One approach calls for using fewer distinct assignments. Instead of using a separate assignment shape
for each workbasket, use When records on flow actions that determine if the flow action is available or
not to the current assignee, based on the workbasket that it's sitting on. You would have 6 flow actions
from the one assignment - 3 common flow actions, and the other 3 available (one or another) based on
the workbasket assigned. You can set the processing behind the connector to determine where the
assignment should be placed, but the Router should do the work, and then the When record will
determine which workbasket is to be used.

Another approach, distinct from that suggested above, is to introduce a new shape to make the
determination of which among several assignments to connect to. Use common connectors from that
shape to proceed to the separate assignments. That would work well if all of recipients could use within
reason the same HTML display within the flow action.

How to use Split-ForEach shapes in screen flows

Summary
There are important differences between using a Split-ForEach shape in screen flows as compared to
using this shape in ordinary flows.

Suggested Approach
The following is a properties panel for a Split-ForEach shape in a screen flow:
The differences between these properties and those available when using a Split-ForEach shape in a
regular flow are described below.

Iterate mode only — The only flow processing mode is Iterate, which spawns flows for
elements of a Page Group or Page List property. Therefore, there is no Join field available in
the panel.
No When or Exit Iteration When options — Because screen flows do not support either of
these when conditions, these options are not available.
No Page Group processing options — Page Group properties are processed in an
indeterminate order and all pages are shown. Page Groups iterate in whatever order the
clipboard has the pages in (see example below). You cannot define different order as you
could in a regular flow. Therefore, the Pagegroup-specific iteration settings options
(Subscript Order, Exact Match?, and Remaining Pages) are not available.
Entry Point links — Links are displayed according to the type of harness you use. Links in a
perform or a screen flow harnesses display as a breadcrumb trail. A tree navigation screen
flow harness displays tree nodes. A tabbed screen flow harness displays a tab. If you click a
navigation link for the Split-ForEach shape, you return to the first step (assignment) and the
split runs again. You can click on links in the tree and breadcrumb harnesses to return to any
step (subflow) within the flow.
Header labels — When you select Subflow Entry Pts?, you can select a property in the Label
Property field. The property is used for the navigation labels used on subflow tab headers or
tree nodes.

You can create a property that will enable you to distinguish each of the pages in the tabs. For instance,
assume that your screen flow uses a Split-ForEach shape named “MySplit”. On the work object, three
pages are referenced by “MySplit”. You want each tab to have a different label rather than all of them
saying "MySplit". In this example, the Split-ForEach shape uses a Page Group property named
.aPageGroup. Each page of the Page Group has a property .aStringProp, which is used as the header
label property. Here is the Page Group on the work object:

The value of .aStringProp is used as each tab’s label. In the above example, the subscript order is RED,
BLUE, then GREEN. Here are the resulting tabs:

Managing migration of updated flow rules into production

Summary
A developer asks: We are looking for best practices for managing the impact of RuleSet version updates
that are deployed into a production environment. In summary, we need best practices and supporting
tools to assess, control, and manage the impact of rule changes with regard to existing work objects
and other historical class instances.

We have two main scenarios:

1. In a higher version, flow rules are updated, assignment tasks within them are modified or deleted,
but in production there are open work objects that reference those assignments.
 2. In a higher version, rules are introduced that reference properties that do not exist on older work
objects, assignments, or other persisted objects.

We've thought of some ways to address these, but none feel comprehensive:

Implement the ProblemFlows flow to trap flow errors.

Run batch jobs to update historical objects to add new property values.
Thorough application of validation rules to check for missing properties .
Use declarative rules and backward chaining to set missing property values.
Running referencing rules reports to access the impact of changes
.

Suggested Approach
One way to address the situation you describe is to use the date circumstance feature and the
pxCreateDateTime value of the work object.

Date circumstancing lets you tie a rule to a date value in a property of the primary object.

By following this approach, you can limit the new flow rules to apply only to those work objects that are
created after a specific date.

An alternative suggestion: For no-longer-needed assignments in the higher versions of the flows, delete
the connectors that lead into discontinued assignments. But don't delete the assignment shapes
themselves.

You'll get the behavior you want because no more flow executions can reach theses assignments, but
any work objects already at those assignments can advance through the updated flow.

Related topics
Upgrading flows that are already in production

Upgrading Flows That Are Already In Production

Summary
Once an application is in production, developers must take care when updating flow rules already in
use. Some developers mistakenly test such changes (in a development system) with only new work
objects. Later, when their updated — but poorly-tested —flow rules move to production, the
assignments on older, existing work objects fail.

Failure to consider open work objects progressing through updated flows can result in problem flows,
stuck work objects, assignments in error, orphaned assignments, and other errors.

This article lists the advantages and disadvantages of four approaches to this design issue. Choose the
approach that best fits your needs.

Suggested Approach
Background
Pega Platform lets you "build for change." This means that existing assignments and work objects in the
system automatically pick up many of the latest changes to your flow rules.

For instance, if you update a flow rule to add an additional local action to an assignment shape, users
can perform the new local action for existing assignments in the production system, even assignments
that were created long before you changed the flow rule.

Each assignment object (such as instances of the Assign-Worklist or Assign-Workbasketclass) records

the following information about their parent flow rule:

pxTaskName— The Visio-generated shape ID of the assignment shape it is linked to.

pxTaskLabel— The developer-entered text label of the assignment shape.
pyInterestPageClass - The first key part of the flow rule (pyClassName).
pyFlowType — The second key part of the flow rule.

As you can see, the pzInsKey of the flow rule, which uniquely identifies the rule, is not stored, by design.
What sorts of changes to a flow can cause problems?

Removing an assignment shape for which one or more open assignments exist. The old
assignments become "orphans".
Replacing an assignment shape. If you remove an assignment from the flow diagram and later
replace it with a new assignment giving it the same name, internally it may have a distinct name.
Flow processing relies on an internal, Visio-generated name for each shape.
Removing or replacing the other wait points in the flow, such as the Subflow shape and the Split-
for-each shape. If you examine an embedded flow page of a work object, you'll see that it keeps
track of the shape ID in the parent flow.

Approaches to safely changing flows

No approach among the following is always best. Each configuration and business setting is is different
and so you must choose the one that best fits your needs.

Approach 1: Create distinct flow rules, either by choosing new flow names or by circumstancing,
leaving the old flow ones as they are.

Copy and clear the Creates a new work object check box on the old flow rules, and check the
Creates a new work object box on the new flow rules, so that new work objects are based only on the
new flows.

If you choose circumstancing, you probably want the default v to be the new flow (in the higher version
number), and the circumstanced version to be the older one. You'll probably want to use date
circumstancing as opposed to property circumstancing.

After these changes are moved into production, the New Work gadget will then list only the new flow
rules, and new work objects will thus execute using the new flows.

This is straightforward to implement, provided your flows aren't too deeply nested with
Advantages
subflows.
After a few releases, your set of flow rules will grow and maintenance may become
difficult, especially if a mix of assignments pointing to the various versions is in
Drawbacks
production. This approach is not recommended if your changes require you to modify 4+-
level deep subflows.

Approach 2: In the updated flow rules, leave all the old flow wait points unchanged. (Assignment,
Subprocess, Split-for-each). Drag these shapes off to one side.

To ensure that flow processing does not drop these shapes when the flow rule is saved, add a
placeholder ticket that connects to these shapes. Keep their outgoing connectors intact.

This way, new work objects never reach these outdated shapes, but the work objects at older
assignments will still follow the same path.

At some point later, you can run a report that checks whether the old assignments are no longer in use.
If so, you can then remove the flow wait points in the next version of the flow.

Advantages: This allows all your work object to use the same rule names across multiple versions
This may not be a feasible solution depending upon your configuration changes. This
Drawbacks:
approach produces cluttered Visio diagrams.

Approach 3: Add tickets in the newly modified flows to control where processing of each type of old
assignments is to resume processing. Run a bulk processing job that finds all the outdated assignments
in the system. For each assignment, the bulk processing should call Work-.OpenAndLockWork, then call
Work-.SetTicket on the work page.

Advantages: Leaves your flow rules clean. Best accomplished as an overnight job.

This approach may be impractical if the set of assignments is too large, or if there is no
moment when the background processing is guaranteed to acquire the necessary locks.
Drawbacks:
Also, an administrator may have to run this bulk processing activity several times until
all the assignments are successfully locked and updated.

Approach 4: Revert the user's RuleSet list to the original, lower versions when dealing with the older
assignments.
 When the changes between versions go beyond just the flow rules, this is the only sure
Advantages:
approach.
This may easily have unintended consequences, where desirable fixes in the higher
Drawbacks: RuleSet version aren't executed because the user's RuleSet list is too low to include
them.

Conclusions

Using one or a mixture of these approaches allows you to successfully navigate the challenge of
updating flow rules that are already in production.

The most important thing to remember is to always test updated flow rules with existing work objects,
not just newly created work objects.

If you do encounter problems and some assignments become problem assignments, utilize the problem
assignment list view to make bulk fixes as necessary. In V5.1, you can access the problem assignment
list view from the Developer portal. Select View > System >Assignment Errors. ( In older versions you
can also access it from the Problem Work link on the Dashboard.)

NOTE: As noted above, if you remove an assignment shape and replace it with a new one but keep the
label the same, the internal Visio ID changes. In flow rules first saved before V4.2, the label and Visio ID
are often the same, but since V4.2 added assignment shapes have an ID like "ASSIGNMENT51".

So an error message such as "The task ‘Development’ cannot be found in this flow” can be confusing,
because you see that the label is unchanged, but the error reports the Visio ID, not the label.

Working with Smart Shapes

Summary
Beginning with PRPC 7.1, the Process Modeler includes a Smart Shapes palette that provides a set of
frequently-used, pre-configured utilities and subprocesses. These shapes can be used in process flows
with little to no additional configuration—you can add, delete, and edit Smart Shapes as you would any
of the other Process Modeler shapes.

Smart Shapes are purpose-built. They are quickly and easily implemented, and provide only the settings
that you need. Additionally, the Properties panels are easy to understand and to configure.

Example Usage
For instance, in PRPC 6.3, you would use a Utility to send an email by adding a Utility shape and
entering CorrNew in the Properties panel's Rule field. The appropriate Parameters settings
automatically populate the Utility tab. However, many of the settings are optional, rarely used, or
labeled in technical terms that may not be understood by all team members.
In contrast, to accomplish the same task in PRPC 7.1, you add a Send Email Smart Shape , which
presents only the settings that you will likely need in your configuration.
Adding Smart Shapes
When working in Process Modeler, display the Smart Shape palette by selecting the Flow Shapes icon
on the header , or by hovering your mouse pointer over the design canvas and selecting Add >
Smart Shapes:
 The yellow shapes, such as Attach Content and Change Stage, represent utilities.
The blue shapes are processes.

When working in Case Designer Process Outline view, you can also select Smart Shapes from the step
tree in the left panel by hovering your mouse pointer over a process shape and extending the Add
Shape menu.
 To view, update, or edit a Smart Shape's properties or parameters, hover your mouse pointer over
the shape, right-click, and select View Properties; or double-click the shape.
To see the shape's underlying activity or process, right-click a Smart Shape and select Open
Activity or Open Flow.

Use in stand-alone or multi-step processes

You can use Smart Shapes in either stand-alone processes or within a multi-step process,
whichever configuration best suits your requirements.

For example, here is an Add Email Smart Shape in its own Send Email process.

The process is employed as a step in the Rejection stage:

Here are Send Email Smart Shapes in the Approvals process:

Smart Shape summaries
The following sections briefly describe how each Smart Shape is used, and provide simple usage
examples.

Smart Shape Description

Attach Content Attaches a file, URL, or note to a case.
Change Stage Automatically advances a case to next stage or or a stage you specify.
Create Case(s) Creates a top case, or one or more subcases.
Create PDF Generates a PDF file from a user form section.
Persist Case Change a temporary case to a permanent one, committing it to the database.
Post to Pulse Posts a message to the PegaPulse social stream.
Push
Pushes a notification of available work to a user's mobile device.
Notification
Send Email Sends an email to an address or to a Party associated with a case.
Using a transform record, updates properties in a case you specify, or all child
Update a Case
cases and descendants.
Cascading Creates a case approval list, which the system uses to route a case to the
Approvals appropriate manager(s).
Duplicate Search Defines matching and weighted case criteria to determine possible duplicate cases.
See Developer Help for Pega 7 for more information about the available settings in each Smart Shape.

Attach Content
Use the Attach Content Smart Shape to automatically attach a file, URL, or note to a case.

For example, you can attach a file that has been defined in the case type record's Attachment Category.
In this example, a category named "VendorProfile" is associated with a Word document, as shown here:
The case type's category and file associated are defined on the case type record's Attachment
Categories tab.

Change Stage
For a case with stages, the Change Stage Smart Shape allows operators to route a case to either the
next stage or to a specified stage.

In this example, a case type process contains an Approval primary stage and a Rejection alternate
stage.

The Get Program Approval step on the Process Overview page includes a "Get Program Fund Owner
Approval" assignment. This is connected by a Reject flow action to the Change Stage Smart Shape
named "Rejection", as shown here:
The process is configured so that if a case is rejected, it is routed to the Change Stage Smart Shape. It
is defined to route the case to the Rejection stage.

When the operator processes an approval, the Reject flow action is available. When clicked, the case is
routed to the Change Rejection stage and undergoes the steps defined for it, Send Email and Reject.

Create Case
Use the Create Case Smart Shape to create a top case, a single subcase, or multiple subcases.

In this example, a Purchase Request case starts with a Request Entry stage followed by a Vendor
Addition, which contains a Create Vendors step:
The step process looks like this:

While entering line items in the Request Entry stage, the operator can add a new vendor for each item.
Here the operator adds a vendor named "Talon Inc.", which supplies desk chairs.

When Request Entry is complete, the system advances the case to the Vendor Addition stage.

The Create Vendors step (Create Case) automatically adds a subcase in case type Vendor Maintenance
for each added vendor:

Here are the Create Case parameters:

Note that the Create multiple subcases radio button is selected. For each line item, the system creates
a unique subcase.

A data transform record named "CopyVendorToVM" initializes the values of the Vendor Maintenance
subcase, which can be copied from the source page SourceLineItem. Note that the source page is
referenced in the Source column on the .VendorSearchValue row, as shown here:

The Vendor Maintenance subcase (VM-21) was created when the vendor Talon Inc was added to
the request for desk chairs. Here is how the subcase appears in the Purchase Request (PR-50) review
form:

In addition to using a Create Case Smart Shape to your process diagram, you can also add a Create a
Case single-step process to a stage from the Stages & Processes tab by adding a step and selecting
Case as the Step Type as shown below:
Create PDF
Use the Create PDF Smart Shape to convert a section to a PDF file and attach it to a case. In this
example, the Smart Shape is configured to convert the Approve section used in the Approve flow action.

The Create PDF settings look like this:

When the process completes, the PDF appears as an attachment on the Review harness as shown here:
Opening the PDF displays the section and its contents:

Persist Case
Use the Persist Case shape in your flow when you would like the convert a case was created as a
temporary object to a permanent object by writing it to the database. You do not have to make any
entries in the property panel for this shape.

In this example, verifying a customer address on a purchase request form consists of two stages:

In Stage 1, the customer's address on the form is matched against the address on the department's
most current customer list.

If the addresses match, the temporary case is resolved—no further processing is necessary.
If the addresses do not match, the case is made permanent and advances to Stage 2.

The case begins Stage 1 as a temporary object in the Match data to customer list starting process.
Note that the Temporary object? checkbox is selected on the record's Process tab:
The process indicates that if the addresses do not match, the case is made permanent in the Persist
Case Smart Shape, and continues to Stage 2 for further research and updating.

Post to Pulse
Use the Post to Pulse utility to automatically create a post to the PegaPulse social activity stream.
Options enable you to associate the post with the current operator or an operator that you specify. You
can also associate the post with a case or allow only operators associated with a case to view the post.

The Smart Shape is configured as shown here:

When the process is complete, the post appears on the case's Review harness, as shown here:
Push Notification
Use the Push Notification Smart Shape in a flow to "push" a notification to users indicating that an
action is required.

In this example, placing the Push Notification Smart Shape before an assignment shape creates an
action that automatically sends a notification to the user's mobile device indicating that an appraisal is
ready for their review.

For more information on configuring an app to use push notifications, see How to use push notifications
with a hybrid mobile application.

Send Email
Use the Send Email Smart Shape to automatically generate an email. In this example, a standalone
process called Send Email is used in a Rejection stage.

The shape uses parameters defined in the flow record that enable you to reuse the flow in more than
one stage throughout your application.

Here are the parameter settings in the flow record:

The Send Email Shape parameters are configured as shown here:

On the Stages & Processes tab, open the Send Email step in the Rejection stage to show the parameter
settings. The Purchase Request Rejection template is used:
The Send Email process is also used as a step in the Procurement stage:

However, the Purchase Request Confirmation correspondence template is used in this context.

Update a Case
Use the Update a Case Smart Shape to apply a data transform that updates a single case (as defined by
its ID), or all child cases and their descendants.

In this example, a Create Case Smart Shape in the Purchase Request case type creates subcases in the
Purchase Order case type. Before this occurs, the Update Case shape applies a data transform to so
that all the subcases use the default addresses:
Here is how the Update Case parameters are set:

Cascading Approval
The Cascading Approval Smart Shape allows you to create an approval workflow in your application. Use
the Smart Shape's properties to create a list of approvers based on a Page List and property (Authority
Matrix), or manager settings in operator or work group records (Reporting Structure).

The Smart Shape's standard subprocesses named Cascading Approval (pxCascadingApproval) and Get
Approval (pyGetCascadingApproval) use the list to route cases. You can configure these processes to
suit your requirements by copying them into your application.

For example, the Cascading Approval properties use an Authority Matrix; the Page List and property are
determined by the results of a decision table.
For a detailed description of the Cascading Approval Smart Shape and how to use it in your application,
see Route cases for approval with the Cascading Approval Smart Shape.

Duplicate Search
The Duplicate Search Smart Shape (using the standard process pyDuplicateSearchCases ) compares a
case to other cases (with same case type) to find any potential duplicates.

The search is based on criteria in a Case Match rule, which you define by accessing the Duplicate
Search option on the Case Designer Details tab. In the Duplicate Search dialog, you create weighted
match conditions and specify a threshold for the sum of the conditions. When a case meets all of the
Must Match conditions and the threshold for the sum of the Weighted Match conditions, it meets the
criteria for being a potentially duplicate case.
The Duplicate Search process compares the current case to already-created cases of the same type to
search for potential duplicates. The flow action, pyDuplicateSearchCases, presents the list of potential
duplicate cases to the user who can determine if the cases are duplicates.

The users can choose to resolve the current case as a duplicate by selecting it from the list and
removing it from further processing.

If none are duplicates, users can cancel and go to the next step.
If there are no potential duplicates found, the user is not prompted, and the flow continues
processing.

Service Levels and Escalation

How to monitor the size of workbasket backlogs
Summary
A developer asks:

Service level rules (SLA's) are associated with a particular work object. How can I build serve level rules
that instead operate against a workbasket?

We have a customer who wants to cause action based on the condition of a workbasket rather than any
particular item. For example, the service level might send an email to management when the
workbasket queue contains more than 25 items, or when the average time in the workbasket is more
than an hour.

Suggested Approach
Service level rules are designed to provide the features that your businesses need to in turn meet the
service level objectives that they commit to their clients.

Those operate on a work object or assignment basis and are not related to workbasket queue metrics.

What you need in this situation is a mechanism for alerts, not service level rules.

1. Create an agent that runs periodically and executes an activity that tests the conditions, such as
the length of the workbasket queue or the average wait time of the assignments in the queue.
2. If the agent detects an out-of-bounds condition, a best practice is to create a work object and route
that work object to the person who needs to take action.

Be careful when selecting the agents' execution interval. Consider related issues, such as how many
times you want a notice sent when a workbasket crosses the limits. One work object can deal with the
full set of alerts.
How to set SLA for next business day calculated in user's
time zone instead of GMT
Example
You want to define a Service Level Agreement (SLA) for the next business day when the current date
and time is not a business day. You want the SLA goal and deadline to be calculated in the application
user's time zone, not in GMT.

Here are the conditional statements that meet your requirement:

If incoming work is not during a business day or is after 3:00 p.m. on a business day, set the SLA
deadline to midnight of the next business day.
If incoming work is during a business day and prior to 3:00 p.m. on that day, set the SLA deadline
to midnight of that day.
All times are relative to the application user's time zone.

In PRPC 6.2 SP2, Pega-provided functionality cannot fulfill this requirement. However, you can write a
custom function rule (Rule-Utility-Function rule type) to get a specific time on a given day and use the
function in an activity. The custom function and the activity described in this article are available in
Pega 7.

Suggested approaches
Choose one of the following approaches:

Upgrade your PRPC 6.2 SP2 deployment to Pega 7.

Create a custom function getSpecifiedTime and use it in an activity called figureOutSLATime.

Upgrade to Pega 7
1. From the PDN Deployment Guides page, specify any version of Pega 7.
2. Scroll to find and select the PegaRULES Process Commander Upgrade Guide, Version 7.1 or later
version guide.

Create a custom function getSpecifiedTime and use it in activity

figureOutSLATime
The following example shows how to define the business logic for a custom function, getSpecifiedTime,
and how to use the function in an activity called figureOutSLATime. The activity figureOutSLATime sets
the SLA goal and deadline properties used in the SLA rule. The activity must be called prior to reaching
the assignment shape that uses the SLA rule.

Example business logic

If current time is not on a business day,

Set SLA Goal to 8:00 p.m. on the next business day and

Set SLA Deadline to 11:59 p.m. on the next business day.

Else If current time is before 3:00 p.m.,

Set SLA Goal to 8:00 p.m. on the current business day and

Set SLA Deadline to 11:59 p.m. on the current business day.

Else

Set SLA Goal to 8:00 p.m. on the next business day and

Set SLA Deadline to 11:59 p.m. on the next business day.

Times must be calculated in the current user's time zone, not in GMT.

Create the function getSpecifiedTime

As an example, the following screen shows how to create the function, getSpecifiedTime, to perform the
business logic.

The Java code is as follows:

DateTimeUtils dtu = ThreadContainer.get().getDateTimeUtils();

java.util.Date theInputDate = dtu.parseDateTimeStamp(inputDateTimeStamp);

if (theInputDate == null)

return "";

Calendar calDate = Calendar.getInstance();

calDate.setTime(theInputDate);

calDate.setTimeZone(TimeZone.getTimeZone(timezone));

calDate.set(Calendar.HOUR_OF_DAY, hours);

calDate.set(Calendar.MINUTE, minutes);

calDate.set(Calendar.SECOND, seconds);

calDate.clear(Calendar.MILLISECOND);

java.util.Date theOutputDate = calDate.getTime();

return dtu.formatDateTimeStamp(theOutputDate);

Use the function getSpecifiedTime in the activity figureOutSLATime

The following screens show how to call the getSpecifiedTime function in an activity called
figureOutSLATime. The SLA goal is 8:00 p.m.

Activity figureOutSLATime, Step 1, Get current time

Activity figureOutSLATime, Step 2, Get next business day goal and deadline
Activity figureOutSLATime, Step 3, If current time is not a business day

Activity figureOutSLATime, Step 4, Get 3:00 p.m. today

Activity figureOutSLATime, Step 5, If current time is after 3:00 p.m., use next business day (NBD) goal
and deadline
Activity figureOutSLATime, Step 6, Else use current time as goal and deadline

How to set the Service Level Agreement (SLA) Late event

from a property reference
Summary
If you look at the Service Level form, you see that the Goal and Deadline intervals are configurable using
a property, but the Late interval (also known as the Passed Deadline) is not. If you need to specify the
Service Level Late interval (the Passed Deadline event) using a property reference, follow the procedure
in the Suggested Approach.

Suggested Approach
To specify the Service Level Late interval (the Passed Deadline event) using a property reference, follow
these steps:

1. In the Service Level work form of your application, under the General tab, specify the Passed
Deadline with non-zero values for the days, hours, minutes, and seconds.

These values won't be used because of actions taken in subsequent steps, but they must be

specified.

2. Specify the Late time interval in the deadline activity:

1. On the Pages & Classes tab, define queuePage as type System-Queue-ServiceLevel.
 2. Create two steps in the deadline activity that both use queuePage as the Step page.
The first step is a property-set that sets pyMinimumDateTimeForProcessing to the
desired value.
The second step performs an Obj-Save with deferred Write.

You might want to add another step to your deadline activity that sets
newAssignPage.pxLateTime to queuePage.pyMinimumDateTimeForProcessing and follow that
with an Obj-Save deferred of newAssignPage, as shown.

The Late time calculated from the values specified in the Service Level form is still set in the
Assignment in the property pxLateTime. However, the time that is set on the queuePage is
what matters in terms of when it executes; it may be confusing to have them differ.

3. Repeat this procedure similarly in the late activity if you need to specify multiple late events.

Additional Information
About Service Level rules

Service Level Form - Completing the General tab

How to set a service level for a work item

Service level rule - definition

Deadline - definition

How to test service level rules through fictitious date

settings on VMWare-hosted systems
Summary
In a development environment, it may be necessary to test future events.

For example, if you create and test an service level rule that has a deadline three weeks from today,
you need to verify that the service level rule works and the resulting workflows process correctly.

Suggested Approach
You can configure a test environment on VMware to set the system date/time to a specific future
date/time required for testing and verifying a function or workflow.

To accomplish this, you need to have your entire environment running on VMware in one of the
following scenarios:

Run one large VMware session containing all the pieces of your environment (Process Commander,
application server, database, etc.).
Run multiple VMware sessions, each containing part of your environment.

By default, VMware synchronizes its system time with that of the host machine. You can disable this
synchronization to set the VMware date/time to any value necessary. To disable the system time,
access the virtual machine’s configuration file (.vmx) and set the following parameters to FALSE:

tools.syncTime<br />time.synchronize.continue<br />time.synchronize.restore<br />time.synchronize.resume.disk<br

/>time.synchronize.shrink

To set the system date, use the date/time function of your operating system

Related topics

For more information see the VMware knowledgebase article

http://kb.vmware.com/selfservice/microsites
/search.do?cmd=displayKC&externalId=1189

and the Keeping a Fictitious Time In a Guest System section of the following PDF document:

http://www.vmware.com/pdf/vmware_timekeeping.pdf

Naming conventions for service level rules

Summary
A developer asks: What is the best practice regarding overriding standard service level rules?

I know service level rules are subject to normal rule resolution. But I have heard advice that service
level rules I create must have unique names so the Pega-ProCom agent finds them and runs them
correctly.

Suggested Approach
Some developers use distinct names that do not match any standard service level rules in the Pega-
ProCom RuleSet.

For example, rather than to override the Work-.Default service level rule, they choose names such as
Default2 or DefaultA.

Their rationale is that if, in a production or other non-development system, someone fails to put an
appropriate access group in the governing Pega-ProCom Agent Queue instance, users may never realize
that the service level rules executing are not from the application, but rather are the standard rules of
the same name.

If the names differ from standard rules and the same access group error is made, no service level rules
execute at all. This is likely to be noticed promptly.

Even if you choose to follow this approach, it doesn't imply that every service level name should be
unique. When you have a flow at an abstract class level and two different work classes that descend
from that, you should use one common service level name and allow rule resolution to determine the
correct service rule.

Service level calculations do not depend on the time zone of

the assignee
Summary
A developer asks: We would like service level rules to be sensitive to the time-zone of the office work is
assigned to.

For example, consider a service level rule that only takes into account business days.

If an object is created at Friday, 3 PM in Los Angeles (Pacific Standard Time) and routed to a West Coast
office, then the service level timer starts immediately. On the other hand, if an object is created at
Friday, 3 PM in Los Angeles and routed to an East Coast office, the service level timer should start the
following Monday.

Can our application implement such service level processing (without going beyond the guardrails)?

Suggested Approach
Determining a service level rule based upon to whom an assignment is routed is antithetical to the way
assignments are created. Service level goals and deadlines are defined before the routing activity is
called.

That means in this case routing needs to be done before reaching the assignment. An acceptable way
to accomplish this is:

Your decision rule could also determine a value for the pyCalendar property on the work object. The
pyCalendar property determines which calendar data instance is used when performing business day
calculations in service level processing.

The important things to remember are:

Service level times are defined before routing is done

The pyCalendar property controls which business calendar is used.

Use the OverallSLA flow to associate a service level with a

work object (rather than an assignment)
Summary
Service level rules define time intervals known as goals, deadlines, and late intervals. These time
intervals define the amount of time an assignment or process should take to complete.

Typically, service levels are associated with individual assignments. However, what if the time spent on
individual assignments isn't important, but the entire process must be accomplished within a specific
amount of time? In this case, you can associate a service level rule with the work object itself.

How it Works

After a service level rule has been configured for a work type, whenever a work object from that class is
created, a standard flow named Work-.OverallSLA starts running in the background. In its default state,
the OverallSLA flow creates an assignment named SLAProcessing in the default workbasket for the operator's
organization.

This assignment stays open until the work object is resolved. The times specified in the work object's
service level are tracked against the SLAProcessing assignment. Additionally, the OverallSLA flow appears
in the clipboard as one of the executing flows on the pyWorkPage page:
The OverallSLA flow has few component parts. It has an assignment, a router, and a ticket. Examine this
flow to determine whether the design needs of your application require it to behave differently. For
example, it is likely that you will want to change the behavior of the router (ToOverallSLA). If so, save
the flow and its component parts into the appropriate RuleSet and make your changes there.

Suggested Approach

To associate a service level rule with work objects, you specify it in the model for the work class.
Complete the following steps:

1. Create the service level rule. (From the Rules by Type explorer, select Process > Service Level.)
Here's the Work-.Default service level rule.

2. Locate and open or create the pyDefault model rule for the work type of the work object for which you
created the service level rule (Rules by Type explorer > Technical > Model).

3. In the model rule, configure an entry for the pySLAName property that specifies the name of the
service level you created. Save the Model . For example:

Now when you create a work object of that work type, flow processing tracks the service level for the
work object against the SLAProcessing assignment. Note that because you specify the service level in a
model for the work class, the service level applies to all flows that create work objects of that class.

Note: Remember to verify that the OverallSLA flow routes the SLA assignments appropriately for your
application, to a person or workbasket that someone is monitoring..

Work Item Attachments

Apply Hfix-3107 to enable drag and drop for file attachments
To enable file attachments to be added to work objects using drag-and-drop in Process Commander 5.5
SP1, apply HFix-2480.

1. From the Hotfix Self-Service site, download HFix-2480.

2. Using Update Manager, install the hotfix.
3. Add file attachments using drag-and-drop as described in this article.

Suggested Approach

How to drag-and-drop file attachments

The following scenario presents use of this feature after the hotfix is installed:

1. Open the History and Attachments window for a work object or choose the local action Add
Attachments.
2. In the Attachments section, click New > Attach a Fileto display the screen for attaching new files.

3. Select the Drag and Drop Mode to checkbox to display the page icon under the Subjectfield.
4. Drag a file from your Windows Desktop or any folder in Windows Explorer onto the drop zone
within the page icon.
5. Hold the mouse pointer over the page icon until a plus sign indicates when you have reached the
target drop zone.

6. After you release the mouse button to drop the file, the file name displays in the File field
(confirming that the Windows Attachment Manager has a handle on the file).

7. Specify the Subject and click OK to upload the file.

Configuration: Working with the property Data-
WorkAttachFile.pyDragDropOrBrowse
After applying HFix-2480, notice that the Drag and Drop Mode checkbox appears in the Layout of the
standard section rule Data-WorkAttach-File.AttachingScreen.

When new file attachments are added, the property Data-WorkAttachFile.pyDragDropOrBrowse is set on
a model (pyDefault). This property determines which user interface control is displayed for adding
attachments to work objects: Browse or Drag and Drop Mode.
 When the property pyDragDropOrBrowse on the pyWorkAttach page is set to false, the Browse
button displays in the work object window for adding attachments.
When the property pyDragDropOrBrowse on the pyWorkAttach page is set to true, the Drag and
Drop Mode checkbox displays in the work object window for adding attachments.

Viewing the Clipboard, you can see, for the class Data-WorkAttach-File the page pyWorkAttach, the
property pyDragDropOrBrowse.

Known limitations
The following limitations apply:

1. This feature only works with Microsoft Internet Explorer and Process Commander 5.5 SP1 with
HFix-2480 installed. The feature does not work with Firefox.
2. You can drag-and-drop attachments one file at a time. Drag-and-drop of multiple files is not
supported.
3. You can drag files only from the Windows desktop or from a folder in Windows Explorer. You
cannot drag an email message from Microsoft Outlook or from another email client into the drop
zone.
4. The file being dragged and dropped becomes a work object attachment. Customization is required
if you want to have the file attached elsewhere in your application.

How to access attachments to covered work from the cover

object
Summary
Giving users access to all work object content such as correspondence, reports, faxes, and photos helps
provide a comprehensive view of a case and encourages work collaboration. As of V6.1, the History and
Attachments display of a cover work object lists its own attachments and those of its covered objects. If
the covered object is also a cover, the list includes the attachments associated with all levels of work
objects.

This article describes which attachments are visible to users in application that involve covers.

Note: You can define covered work by adding a case type rule (Rule-Obj-CaseType) to a cover class.
See How to create an application using covers within covers.

Suggested Approach
Below is the class structure of a sample auto insurance case management application. Text in each box
shows the work object description, prefix, and work type.

In this example, the Vehicle Accident Claim top-level cover class contains a case type rule that covers
Bodily Injury and Vehicle Damage. Each of these classes contain a case type rule that covers their
covered work types. The case manager can access attachments to any of the inherited objects. Users at
lower levels in the application hierarchy can view attachments to their inherited work types.

The case manager created top-level case C-1 and then created CC1-1 and CC2-1. The user accessing
CC2-1 created PO-1. The user in CC2-1 created work objects VA-1 and VA-2. The work objects have
these attachments.

Vehicle Damage (CC2-1) — Correspondence from attorney of insured

Value Assessment (VA-1) — Word file containing Acme Co. estimate
Damage Appraisal (DA-1) — Photos taken at accident site
Police Report (PO-1) — FAX of officer's statement

Because Vehicle Accident Claim is the parent or grandparent to all the work objects, the C-1 case
manager can open all the attachments.

However, a user who is accessing in work object CC2-1 can access documents attached to VA-1 and DA-
1 but not to PO-1. This objects is a child of CC1-1, which in turn is a child of C-1. CC1-1 is a peer of CC2-
1. Users accessing PO-1, DA-1, and VA-1 can only open their own attachments.

How to attach a binary file to a work object

Summary
Your application users can attach files to work objects through the History and Attachments display such
as a scanned image of a paper letter or form. However, your application may require attaching one of a
set of fixed files to a work object (so that the file can be included in outgoing correspondence).

For example, assume that you have ten short movies (such as AVI files for Windows Media Player
format or SWF files in Adobe Flash form) that demonstrate how to fix common problems with a product
. In your application, you can store each movie in a binary file rule and then copy the appropriate movie
to a work object.

Your flow can include an activity that attaches a graphics file (including JPG, GIF, or PNG files) to a work
object. Storing the image or movie in a binary file rule (Rule-File-Binary rule type) provides the benefits
of version control, packaging, and inheritance. The example shown in the procedure below describes
how to build the activity and incorporate it into a flow.

Suggested Approach
In this example, assume that your flow includes a Utility shape that is to attach a binary file instance
called aboutlogo.gif.

Here is the utility shape, which references an activity called CopyBinaryFiletoWorkObj.

Steps
1. Confirm that your Developer portal has the appropriate work pool selected.
2. Select the Application > New > Rule > Technical > Activity menu item. Enter the activity key
parts.
3. Select the Pages and Classes tab.
4. Create and enter a page name for the Rule-File-Binary and Data-WorkAttach-File classes (in this
example, binary and attachPagerespectively). The binary page will hold the binary file rule
containing the image.The attachPage page will hold the new work object attachment.

5. Open the Steps tab. In the first activity step, enter binary in the Step Page field and select method
Obj-open-by-handle, which copies the binary file rule to the clipboard.

6. Enter parameters for this method. For the InstanceHandle parameter, enter the handle of the
binary file rule in quotes. In this example, the handle is the value of the pzInsKey property "RULE-
FILE-Binary WEB ABOUTLOG!GIF #20070320T201009.615 GMT" .
Tip: You can quickly find the pzInsKey for a rule by clicking the RuleData toolbar button while
you are in the binary file rule form.
7. In the second activity step, enter the attachPage (class Data-WorkAttach-File) StepPage and
select Method Page-New.This creates an empty page to which you want to copy the image (which
is Base-64 encoded).

8. In the third activity step, on the attachPage select method Property-Set to copy the properties
from the binary file rule into the attachment.. In the first property row select the PropertiesName
.pxAttachName. In the PropertiesValue, select the page binary and its value .pyFileName. Append
the file extension (+".gif"). Add another property row, select .pyAttachStream, and enter the
second value .pyFileSource for the binary page

9. In the fourth activity step, select Obj-Save to create a database instance of attachPage. In the fifth
 activity step, leave the Page field blank ( indicating the primary page). Select method Link-Objects.
In the LinkTo Page parameter enter the step page called attachPage. In LinkClass, select Link-
Attachment. This page when saved links the work object. to the new file attachment.

10. In the sixth activity step, enter Commit method to write the three instances to the PegaRULES
database and save the activity. It should look like this.

11. Run the activity to validate it. It is suggested that you select Run > Tracer to turn on the Tracer
utility.
12. After validating the activity, delete the Commit step (or make it a comment) since the Commit
happens automatically in a flow execution.
13. Test the flow that includes the activity. When processing completes, open the History and
Attachments display and verify that the image appears as a file attachment.

How to create activities that attach files to work objects

Summary

Because many applications prompt users to attach files such as correspondence to work objects, there
are several standard flow actions that create work object attachments. For example, the standard Work-
.AddAttachments flow action enables users to upload a single file and select a category for it while
Work-.AddMultipleAttachments enables user to select multiple files and choose a category for each.
However, there are times when you need to configure this kind of processing yourself. For example:

If the same file should be attached to every work object from a certain work type, there's no
reason to use a flow action and require user input.
If you are using the SmartForms feature to create PDF forms or documents or to process incoming
PDF forms, you might want to attach the original PDF to a work object. For information about this
feature, see Working with PDF Forms and Documents
If you are configuring an application that enables users to convert Word .doc files to PDF files, you
might need to modify one or more of the standard rules that support the standard Convert to PDF
flow action. This feature is also described in Working with PDF Forms and Documents.
How to configure an email service to use an email attachment as a work object attachment
describes another case in which you need to configure the attachment processing yourself.

This article describes how work object attachments are linked to work objects and explains how to
configure activities that attach files to work objects.

Suggested Approach
A file attachment for a work object is an instance of Data-WorkAttach-File. The attachment is connected
to its work object through a link object, an instance of Link-Attachment.

Work object must exist

The work object must exist before you can create a work object attachment for it. That is, the work
object must be committed, not just saved to the deferred operations list with an Obj-Save method,
before you can attach something to it.

Two parts to attachments

Creating attachments is a two-part process: an activity must create the attachment object (of class
Data-WorkAttach-File) and then it must create a link object (of class Link-Attachment) that connects the
attachment to the work object.

Files must be Base64 encoded

The file must be stream encoded to Base64 before it can be saved as an attachment.

If you are working with the SmartForms feature, you use the AttachEForm activity to save a PDF file
as a work object attachment – it takes care of the encoding.
When an email listener processes an email message, it Base64-encodes any email attachments
and puts them on a page named pyAttachments of class Data-ServiceMessage.
When a user creates an instance of Rule-File-Binary to store an image, PDF, or other binary file,
Process Commander Base64-encodes the file when the file is uploaded.

If the file that you want to attach to a work object has not already been encoded, you must configure
the activity to Base64-encode the file before it puts the file on the attachment page. You can use the
Encode() function from the PegaRULES.Default function library.

Properties to set on the attachment page

When the activity creates the attachment object (of class Data-WorkAttach-File), it must set values for
the following properties:

pxAttachName – the name of the file

pyAttachStream – the Base64 encoded file stream (this is the file itself)
pxAttachedBy – operator ID of the user attaching the file. You obtain this value from the requestor
page. For example, pxRequestor.pyUserIdentifier
pxAttachKey –the date the file is saved as an attachment (a timestamp)
pxRefObjectKey – the pzInsKey of the work object it is getting attached to (pyWorkPage.pzInsKey)
pyNote. Although not a required field, you should always set a value for the pyNote property so an
entry is written in the audit trail (history) when a work object obtains an attachment. Notes are
limited to 60 characters.

Properties to set on the link object page

When the activity links the attachment to the work object, it should set a value for pyCategory on the
link object page. If you do not specify a category, files will be listed under the category “Other Files.”
Summary of Pages and Classes

Following is the list of pages that the activity uses:

pyWorkPage
pxRequestor (of class Code-Pega-Requestor). You use this page to obtain the user identifier of the
operator attaching the file when setting the value of pyAttachedBy
An attachment page of class Data-WorkAttachFile , typically named something like NewAttachment

If you are using the SmartForms feature, you also need a page of class Code-Pega-eForm.

Summary of activity steps

Activities that create the attachment objects and link them to work objects include the following general
steps:

1. Create a page for the work object attachment (Data-WorkAttach-File class).

2. Put the file on the attachment page.
3. Save the attachment page (Obj-Save method).
4. Create a link object (Link-Attachment class) that connects the attachment to the work object with
the Link-Objects method.

There are additional steps, depending on the kind of file and what your goals are. For example, if your
goal is to attach email attachments, you need a preliminary step that extracts the attachments from the
Data-ServiceMessage page. If you are attaching a file stored in the PegaRULES database, you need a
preliminary step that gets the file.

Note: Normal flow processing commits a work object after it has been updated, so in most cases you
should not include a step that commits the work object. If yours is a special case and you do need to
commit the work object during custom processing, use the standard activity Work-
.CommitWithErrorHandling. Do not use the Commit activity method. For more information about when
work objects are committed, see Designing Applications that Ensure Data Integrity.

Examples
In this example, an application supports customer service reps who take mortgage applications over the
phone. A standard privacy policy statement must be attached to all mortgage applications. Because the
privacy policy is the same for all applicants, there’s no reason to require the customer service reps to
manually attach it with a flow action. Instead, a utility activity attaches the privacy policy document to
approved mortgage work objects just before the end flow shape.

The examples illustrate two ways to configure the utility activity.

Note the following:

The privacy policy statement is a flat PDF file stored as a binary file rule (Rule-File-Binary).
Because the activity runs as the last step before the flow ends, it is clear that the work object
exists by the time the activity is invoked.

Example 1: Using activity methods

The first example shows how to use the activity methods Obj-Open-By-Handle and Link-Objects to
create a work object attachment. Figure 1 shows the Pages and Classes tab of the example activity.

Figure 1. Pages and Classes, example 1

In addition to the requestor page, the tab defines a page for the privacy policy binary file (PrivacyPolicy)
and the work object attachment page where the privacy policy file will be copied (AttachmentPage).

Figure 2 shows the steps from the first example activity.

Figure 2. Activity Steps, example 1

Step 1 uses the Obj-Open-By-Handle method to retrieve the privacy policy file from the PegaRULES
database; step 2 uses Property-Set to copy the file to the attachment page; step 3 saves the
attachment page; step 4 links the attachment to the work object with the Link-Objects method.

Figure 3 shows step 1:

Figure 3. Step 1, example 1

The InstanceHandle parameter is set to the value of the binary file rule's pzInsKey property.

Tip: To get the value of a rule's pzInsKey , open the rule, click the Rule Data toolbar button, and then
search for pzInsKey on the page that appears.

Figure 4 shows the Property-Set step (step 2):

Figure 4. Step 2, example 1

This step copies the file to the pyAttachStream property on the AttachmentPage. It also copies or sets
other property values that Process Commander needs to create a work object attachment:
pxAttachName, pxAttachedBy, pxAttachKey, pxRefObjectKey, and pyNote. Note the following:

The value set in pxAttachName includes the file type. If you do not specify a file extension for the
file, Process Commander cannot determine how to display the file when you click it in the
Attachments window of the work object.
The value specified for pyNote ensures that the value is within the character limit (60) for a note.

Figure 5 shows the Link-Objects step, step 4:

Figure 5. Step 4, example 1

This step creates the link object that connects the new work object attachment to the work object. The
step page is specified as pyWorkPage. Therefore, the Link-Objects method creates a link object of class
Link-Attachment (LinkClass parameter) that links pyWorkPage to the AttachmentPage (LinkToPage
parameter), which now has the binary file (privacy policy).

To set additional properties on the link object page, use the LinkPageProperty and LinkPageValue
parameters. For example, to identify a category for the attachment, you specify the pyCategory
property as the LinkPageProperty and specify the category with the LinkPageValue parameter, as shown
in Figure 5.

The Link-Objects method writes the link operation to the deferred operations list. When the activity
finishes and returns control to the flow, normal flow processing commits the work object and the
attachment.

Example 2: Using the standard eForm activities

Because the privacy policy file is a PDF, you can use the eForm activities provided by the SmartForms
feature to attach the file to the work object. This example shows how to use the Code-Pega-
eForm.GetEformFromRuleFileBinary and Work-.AttachEForm activities.

Figure 6 shows what the Pages and Classes tab looks like:

Figure 6. Pages and Classes, example 2

As described in Working with PDF Forms and Documents, the Code-Pega-eForm class is a help class for
working with PDF files. The eForm activities use pages of this class as temporary storage locations for
the PDF files while manipulating the files.

Figure 7 shows the steps.

Figure 7. Activity Steps, example 2

Step 1 creates the eForm page; step 2 calls the GetEFormFromRuleFileBinary activity on the eForm
page; step 3 passes the PDF now located on the eForm page to the Work-.AttachEForm activity, while
creates the work object attachment.

Figure 8 shows the step that calls the GetEFormFromRuleFileBinary activity.

Figure 8. Step 2, example 2

This activity retrieves a PDF form or document from a binary file rule instance and puts it in the
pyEForm property on the eForm page. This activity takes the three keys to the binary rule as input
parameters: Application Name (typically webwb), File Name, and File Type

Figure 9 shows the step that calls the Work-.AttachEForm activity.

Figure 9. Step 3, example 2

This activity retrieves the PDF file from the pyEForm property on the eForm page (PrivacyPolicyEForm)
and links it to the work object on pyWorkPage as a work object attachment. The input parameters for
this activity are those shown in Figure 9. Note the following:

The value for FileName includes the .pdf file extension.

The pyCategory parameter is optional, but if you do not specify a category, the file is categorized
under Other Files in the Attachment window for the work object.
Because this activity is called without user interaction (it's called from a utility activity rather than
a flow action), the SuppressHTML parameter is selected.

Resources
The two activities used to illustrate this article are available here:

PRKB-24121-RuleSet-52 (use for V5.2)

PRKB-24121-RuleSet-53 (use for V5.3)

The activities are named PegaSample-Task.AttachPrivacyPolicy and PegaSample-

Task.AttachPrivacyPolicyEForm.

How to enable users to delete attachments

Summary
Use these two privileges in V5.2 to allow users of your application to delete certain work object
attachments.

Suggested Approach
Work object attachments, like work object history, are in most situations considered a permanent and
unchangeable record of events, evidence, and facts. However, V5.2 includes two new privileges that
allow certain users to delete certain attachments:

Work-.DeleteAnyAttachment — Allows a user to delete any attachment (File, URL, Note,

ScreenShot, or ScannedDocument type) for any work object that the user can update.
Work-.DeleteOnlyOwnAttachment — Allows a user to delete only attachments that he or she
created.

For example, a file could be accidentally attached to the wrong work object. Using these capabilities, a
user could download the file, then detach it from the wrong work object, and later attach it to the
correct work object.

Standard access roles (such as PegaRULES:User4 and PegaRULES:WorkMgr4) do not provide either
privilege.

Also, these privileges do not allow users to delete correspondence items, which are permanent
records of materials sent to others.

To enable this capability in your application:

1. Identify or create an access role to convey the privilege:

2. Create or update an Access of Role to Object rule that has this access role as the first key part: and
Work-. as the second key part. On the Privilege tab, enter the privilege desired, and the production
level of your system. Save the Access of Role to Object form.

3. Update an access group to reference the access role name:

 4. Users associated with that access group see the delete icon ( ) for attachments they can delete.

The Delete icon does not appear for other users who do not hold the privilege.

Tip: Through an Access When rule referenced in the Level field of the Access of Role to Object form, you
can further restrict in which situations the privilege is conveyed. For example, you could allow users to
delete attachments for open work objects but not resolved work objects.

Linking to external documents versus importing them as

work object attachments
Summary
A developer asks: We are migrating to Process Commander and want to move historical data records
that include attached Microsoft Word documents over from an old Sybase system.

Should we copy over the Word documents, or is there another way?

Suggested Approach
The Word documents don't need to be copied over unless there is a compelling reason to do this.
Having only one copy of the documents saves space and eliminates any out-of-synch possibilities.

The work object attachment facilities seem a natural fit, especially if you will have multiple documents
associated with one work object. The external documents can be treated as attachments to the work
object. Any document that can be automatically opened by a URL link can be an attachment. (The
program — such as Word — that displays the document must reside on the user's Windows workstation
and be associated with the file type, such as DOC for Word.

A good way to implement attachment "by reference" is to use a URL that starts an activity. The activity
can perform whatever processing is required to open the actual document (including a Sybase SQL
query, if that's required.)

Work Parties
How to define new properties in a Data-Party class
Summary
A developer asks:

(1) I want to use as much out of the box as I can and override and extend the the work party classes.
However, I want to use State/Province for Province and not have the State property appear at all. How
can I do this?
(2) In addition, I'm having a problem with a summary view report on work objects: I want to display the
property .pyWorkParty(Candidate).pyFullName. I can get this property to display in a list view report,
but I can't save a summary view rule with this property specified in the Drill-Down tab. Why is this?

(3) I want users to be able to add a party in the middle of a flow. How do I do that?

Suggested Approach
(1) Standard Data-Party classes do not let you consolidate the State and Province lists. You must create
a custom party class, and put the required properties into that class.

(2) This problem with the drill-down from summary view report is a bug that has been previously
reported.

(3) You can add a party in the middle of a flow by adding a local flow action to each assignment This
lets users add a party anywhere in the flow they want.

How to use the Split-ForEach flow shape with a repeating

party
Summary
To start a subflow execution for each work party of a type that can repeat, use the Split-ForEach shape.

For example, you can require that each interested party (who are Process Commander users with
Operator ID instances record his or her approval in a subflow, where the current process is resolved
only after all interested parties approve.

In this case, you identify the parties as interested and require their approval separately using a Split-
ForEach shape.

This article describes how to use the Split-ForEach flow shape with a repeating party, where subflows
are started for each party of a specific type ("interested"), but not for other parties in the work object.

Suggested Approach
To set up the Split-ForEach operation:

Specify the repeating party in Work Parties.

Create the Split-ForEach sub-flow.
Call the Split-ForEach flow from your process flow.
Test the process.

Specifying the repeating party in Work Parties

1. Open the Work Parties rule in your application.

2. Make sure that the List of Valid Parties section has a role and party class defined for the repeating
party. In the example, the repeating party is Interested.
3. Enable VOE (Visible On Entry) for the repeating party.
4. Enter the same name in the List Parties that may Repeat section.

5. Save the rule.

Creating the Split-ForEach subflow flow

1. In the example, the approval of all the interested parties is required. You can copy and adapt
a standard approval flow rule for this case. Open the flow rule named Work-
.StandardApprovalsAll.
2. Save it to your application RuleSet.
3. Click the Flow Editor icon to start Visio editing of the flow.
4. Click the Split-ForEach shape to open the Split-ForEach Properties pane.
5. In the When field, select IsInterestedParty from the SmartPrompt list.

1. Click Apply.
2. Click the Save icon.

Calling the Split-ForEach flow from your process flow

1. Open the flow to which you want to add the Split-ForEach operation.
2. Click the Flow Editor icon.
3. Drag a flow shape on to the diagram to be used as a subprocess.
4. Enter a text description in the Name field for the subprocess flow.
5. In the Flow Rule field, select the subflow flow that you just created from the SmartPrompt list.
6. Make sure connector shapes are added as appropriate. In the example, the shapes define approval
and disapproval statuses.

7. Click Apply.
8. Save the rule form.

Testing the process

1. Run the process.

2. On the New harness, enter your interested parties. In the example, the interested parties
have operator IDs, [email protected] and [email protected].
 1. Step through the process until you reach the split operation. In the example, each interested
party is required to approve the purchase order. Note that they must log in under their ID to
record their approvals.

How to use the addWorkObjectParty activity to add a party to

a work object
Summary
You can use the standard activity Work-.addWorkObjectParty to add a work party and its properties to
an existing work object without any user input or interaction. This article uses an example of a purchase
order process to describe how your flow can call the activity

This article describes V6.1 facilities. For a similar task using V5.2, see How to automatically add a work
party to a work object using the .addWorkObjectParty activity.

Suggested Approach
In the following example, you want to configure a purchase order flow so that managers have the email
address of the appropriate vendor work party when they receive orders for approval. Because the
vendor is not known when the order is first created, the person who creates the work object cannot
enter the party information in the New harness.
You want to automate the process so that after the order is confirmed, properties on the work object
identify the vendor and add a populated vendor work party section to the form. The area of interest in
the process looks like this:

Do the following:

1. Create a model in the Data-Party class (or a subclass of that class) that includes the required
properties pyWorkPartyUri , .pxPartyRole, .pyCorrPreferences(1) , .pyEmail1, , and .pyLabel.
properties. In this example, the values are copied from the vendor ID and shipping address on the
work page.

Note: Instead of using a model to set up property values, you can define a a page of the Data-
Party class (or a subclass of that class) as described in Step 5 below.
2. Add the vendor role, party class, and the associated model name in the application's work party
rule (Rule-Obj-WorkParties).

3. Open the flow in Visio, select the ReadyForApproval flow action that leaves the Confirm
assignment, and open the flow action rule by selecting the pencil icon.
 4. On the rule's Action tab, enter the party role, party class, and party model in the After This Action
section and save the rule.

As an alternative to a model, enter a parameter value in the partyPage field to request the top-
level page that has been created.
5. The configuration is complete. Run the flow to test it.

Notes

The Work-.addWorkObjectParty activity has an output parameter PartyIDUsed, which is available to

the calling activity if the parameter page is shared.
This activity does not commit the changes; flow processing commits them later.
A similar standard routing activity Work-.ToNewWorkParty adds a party (always of class Data-
Party-Person) and also routes an assignment to that party.

Use activity addWorkObjectParty to add a party to a work

object
Summary
Your flows can call the standard activity Work-.addWorkObjectParty to add a work party to an existing
work object. No user input or interaction is required. This activity doesn't commit the changes; later
processing in flow processing ordinarily commits them.

This article describes V5.2 facilities. For a similar task using V6.1, see How to automatically add a work
party to a work object using the .addWorkObjectParty activity.

Suggested Approach
The standard activity Work-.addWorkObjectParty can add a party to an existing work object without user
interaction.
This activity accepts up to 7 parameters:

To use this activity:

1. Open the flow rule in Visio. Add a Utility shape to the flow.
2. Complete the Utility Properties panel. In this example, a work party of role Broker is added.

3. If the new access role is not defined in the Rule-Obj-WorkParties rule for the work type update the
rule to include the new work party role.
4. Set up property values for the party in either (or both) of the following ways
Through a model in the Data-Party class (or a subclass of that class). You can identify the
model in the PartyModel parameter of the activity.
Through processing that creates a page of the Data-Party class (or a subclass of that class).
You can identify the page in the partyPage parameter of the activity.

Set all of these properties for the party:

pyWorkPartyUri
pyCorrPreferences(1)
pxPartyRole
pyLabel
pyEmail1

Notes
 1. The Work-.addWorkObjectParty activity has an output parameter PartyIDUsed, which is available
to the calling activity if the parameter page is shared.

2. The activity is one of dozens in the Process Engine API. To see a list, open the Integration slice and
click the Process Engine API link. A similar standard routing activity Work-.ToNewWorkParty adds a
party (always of class Data-Party-Person) and routes an assignment to that party.

Work Item Numbering

Can allow users in distinct organizations to share one work
pool
Summary
Prior to V4.2SP5, problems arose in applications that allowed operators who belonged to multiple
organizations to create work objects in one work pool. However, Process Commander did not detect
nor prohibit such applications.

In V4.1 and early releases of V4.2, if a user in one organization tries to create a work object in a work
pool that already contains work objects from another organization,.the create operation completes and
assigns a work object ID ending with -1, but incorrectly overwrite the previous -1 object in the database
if it existed.

In V4.2SP3 and V4.2SP5, the create operation fails if the object with the same work object ID already
exists.

V4.2SP5 and later versions allow different organizations to use a common work pool.

However, if your system was upgraded to V4.2SP5 and work objects already exist from multiple
organizations ( or work object entry was ever attempted from multiple organizations) in one work pool,
then — immediately after upgrade —a special step is necessary to create the first V4.2SP5 work object.

Suggested Approach
The Data-UniqueID class supports the assignment of work object IDs. Consider this Class Explorer
display:

This report shows that three

different organizations have created W- work objects. Just from looking at the table, you cannot
determine whether these work objects all belong to one class group or various class groups.

However, it is fair to guess that the Pegasystems.com organization, with 1721 entries, is the main
organization that was in use.

A user belonging to that organization should creating the first work object in an upgraded V4.2SP5
system When that first work object is created, Process Commander adds a new instance of in the Data-
UniqueID class with a blank organization and an ID of W-1722. (However, if the first work object is
added in V4.2SP5 from a user belonging to the pega.com organization, the new instance will have an ID
of W-4. This causes conflicts with existing work objects all the way up until 1722.)

If you want some users to execute V4.2SP5 rules and other users to execute V4.2SP4 rules, set the
access group for the V4.2SP4 users to reference version 04-02-62 of the standard RuleSets.

Related Topics
Use distinct work pools or work object prefixes for distinct organizations

How to include a check digit in work object IDs

Summary
As a new work object is created, Process Commander computes a work object ID. The only system-wide
constraint that applies to a work object ID (property Work-.pyID) is that it is unique.

By default, the standard activity Work-.GenerateID uses information in the Data-UniqueID class together
with a supplied prefix string and optional suffix string to assign a unique ID, by adding +1 to the
previous integer value saved in property Data-UniqueID.pyLastReservedID for the prefix. For example, if
the prefix is W-, the suffix is empty, and the last reserved ID is 10, the next work object ID is W-11.

Your application can use a different algorithm to generate pyID values that may be more meaningful to
the user community. Always design the logic carefully to ensure system-wide uniqueness. In this
example, the generated pyID value contains a single check-digit, which significantly reduces the chance
that manual updates to work objects will be made to an incorrect work object because of typing errors.

Suggested Approach
Users — even those who are careful and skilled typists — make errors when typing in sequences of
digits such as work object IDs. A common remedy — used for credit card numbers, Universal Product
Code numbers, and International Standard Book Numbers (ISBN) — is to include a computed check digit
at the beginning or end of the number. The check digit allows the system to detect common errors in
the input of a series of digits, such as a single mistyped digit, or the permutation of two successive
digits.

In this example application, pyID values are assigned in numerical sequence, but a check digit with
value 0, 1, ...9 or X is appended to the value, For example, the 14th work object has check digit 6, so is
identified as W-14-6 (not W-14). The 15th work object has check digit 3, and so is identified as W-15-3.

Costs and benefits

Adding a check digit to a sequence of digits that identifies a record reduces (but does not eliminate) the
chance that an incorrect record is retrieved and processed due to user typing errors. For the Mod-11
ISBN algorithm used in this example, if a wrong digit is typed or two digits are transposed (but the
correct check digit is typed), there is only 1 chance in 11 (or 9.1%) that the result could be a valid work
object ID.

The "costs" of this approach are modest:

Users must type two additional characters when entering an ID

Computations are required to generate the check digit
An activity, library, and function rule are added to the application

Procedure
1. Create a library rule to hold the function rule.

2. Create a function rule in the library to compute and append the check digit.

In this example, the function rule is named CheckSum. On the Parameters tab, identify the input
parameter, as a Java string, which corresponds to the Property type Text.
On the Java tab, enter code to compute a check digit. This example uses the Modulo-11 check sum
algorithm employed for the International Standard Book Number (ISBN) final digit. The final "digit" can
be the single character "X" or 0 to 9.

See //www.isbn.org/standards/home/isbn/international/html/usm4.htm.

Save the function rule form. On the Parameters tab, click Generate Library to compile the function rule.

Note: Since the ISBN algorithm treats digit positions differently, this Check Digit code first pads the
supplied value InputString with up to seven leading "0" characters, creating a starting value that is
always eight digits long.
As a result, the function will not work for starting values of more than 99,999,999. The leading zeros are
not included in the final result.

3. Copy and override the standard Work-.GenerateID activity

Open the standard activity Work-.GenerateID and save it into an application RuleSet, preserving the
Activity Name key part. In this example, the Applies To key part is set to the class group of the
application (MyCo-Emerald), so that the new algorithm is employed for only the work objects in that
class group.

On the Parameters tab, define a local variable TempID.

On the Security tab, select the May Start? check box. On the Pages & Classes tab, add a row for the
Applies To class.

On the Steps tab, insert a new step 3 before the existing Step 3.

In step 3, use a Property-Set method to save the default-generated .pyID value (excluding the leading
two-character prefix) in the local variable. Next, compute the string that includes the prefix, the
generated pyID value, and the check digit.

.pyID = param.IDPrefix +@CheckDigit(Local.TempID)

4. Test.

Save the Activity form. Enter a work object. Confirm that the check digit appears and is computed
correctly.
Using the Class Explorer, you can list the instances of the Data-UniqueID class to see the last ID
assigned for each prefix, to confirm that this change does not affect them. (Although the Data-UniqueID
class has property pyOrganization as a key part, that property is typically blank in Process Commander
applications built since V4.2SP5. This assures that work object IDs with a specific prefix and suffix are
unique system-wide, not just organization-wide.)

Notes
1. In this example, a dash character separates the check digit from the sequential number, Alternatively
the check digit can appear at the front of the sequential number, if separated by the leading zeros.
(Appending the check digit to the beginning or end of the sequence number without a dash or the
leading zeros does not assure uniqueness.)

2. In this example, the Applies To class of the activity is set to the class group of the application. To
have the check digit algorithm apply to all work objects in all applications, use Work- as the Applies To
class of the activity , and make sure the library, function rule, and activity belong to a RuleSet version
available to all applications.

3. This article presents only generation of the check digit. The same algorithm — if re-implemented in
JavaScript rather than Java —can be used to validate a user-typed check digit. Validation catches
errors earlier, as or before the user submits the form.

A client-side validation check also eliminates the network traffic, form processing, and database lookup
operations associated with the incorrect value.

4. For simplicity, the CheckDigit function in this example assumes that the prefix is two characters long.
To make the function more general, use the actual length of the prefix.

Related topics

Understanding work object IDs

How to purge all work objects and restart work ID numbering
Wikipedia's explanation of check digits, at http://en.wikipedia.org/wiki/Check_digit
Make work object IDs unique within application and organization (V4)
About function rules
Make Work Object IDs unique within application and
organization
Summary
A developer asks:

1. What is the expected scope of a work object ID? Is it unique within an application and organization
but not assuredly unique system-wide, say within two organizations?

2. If multiple organizations separately use a single application, but work objects are never transferred
among them, what can be done in the application or deployment to prevent accidental work object
ID collisions and locking issues?

3. If multiple organizations use a single application, each entering new work, but work objects and
transferred among them, what can be done to prevent accidental work object ID collisions?

Suggested Approach
These answers are for V4.2:.

1. Work IDs should be unique within an application and an organization.

2. In the case described, no collision will occur because work objects are not being transferred.

3. If work objects share one class group, collisions will occur. Create a class group for each
organization, even though the application is shared.

Update: Beginning with applications created in V4.2SP5, work object numbers are assigned without
regard to organization, so the specific issue described above no longer occurs.

In V4.2SP5 and later, if both Southern Inc. and Western Corp. use the W- prefix, the work object IDs do
not collide. Rather, the work object IDs are issued in sequence, so that W-124 and W-126 may belong to
Southern and W-125 belongs to Western. See Can allow users in distinct organizations to share one
work pool.

However, to avoid human confusion, using distinct work pools and distinct prefixes is nonetheless a
good design practice.

Use distinct work pools or work object prefixes for distinct

organizations
Symptom
If you have more than one organization defined, and two organization's flow rules create work objects
with the same work ID prefix (such as W-), errors may occur.

Creating the same-numbered work object ("W-3") in two or more organizations causes the history
information for both items to be displayed in each work object. That is, history for the work object in
one organization appears incorrectly in the history for the work object of the other organization).

This problem does not occur if each organization uses a distinct work object ID prefixes for its work
objects. For example, the problem disappears if they agree to use the S- prefix for Southern Inc. and
and W- prefix for the Western Corp.

Update: Beginning with applications created in V4.2SP5, work object numbers are assigned without
regard to organization, so the specific issue described above no longer occurs.

In V4.2SP5 and later, if both Southern Inc. and Western Corp. use the W- prefix, the work object IDs do
not collide. Rather, the work object IDs are issued in sequence, so that W-124 and W-126 may belong to
Southern and W-125 belongs to Western. See Can allow users in distinct organizations to share one
work pool.

However, to avoid human confusion, using distinct work pools and distinct prefixes is nonetheless a
good design practice.

Solution
Workaround

To keep such history data correctly segregated, set up work pools (also known as class groups) for each
organization.

Problem Flows and Assignments in Error

How to specify a Problem Flow operator
Summary
As it executes, a flow may encounter an error condition that prevents it from continuing.

For example, the flow may reference a rule that is not found at runtime.

When this occurs, the system suspends the progress of that flow and notifies the a Flow Problem
operator, who can look into the nature of such a problem and correct the issue such that processing can
resume.

This article summarizes how to identify a Flow Problem operator for your applications.

Suggested Approach
The default processing sets the Problem Flow operator to an Administrator account in the requestor's
organization, such as "[email protected]". This means that all problems from all
applications are routed to a single worklist.

To specify a Flow Problem operator, override the standard activity Work-.getFlowProblemOperator in

your application's work pool and RuleSet, keeping the Activity Name key part.

In your activity, set two parameters OperatorToInform and AssignmentType.

Set the AssignmentType to Worklist or WorkBasket.

If Worklist, set the OperatorToInform parameter to the pyUserIdentifier value of an Operator-ID

instance.
If WorkBasket, set the the OperatorToInform parameter to the pyWorkBasket value of a Data-Admin-
WorkBasket instance.

One suggested approach is for the activity to open a Data-EmailAccount instance from which to read
the Flow Problem Operator information (Account Type of FlowProblem), so that the
getFlowProblemOperator activity can remain static.

How to use the FixWork flow to repair flow and assignment

problems
Summary
An administrator can use the standard Work-.FixWork flow to fix problems with work objects.

Suggested Approach
These actions are available to a administrator:

Find & Fix null assignment pointers

This action allows you to clean up the assignment pointers listed in the flows of the work object. Due to
various flow problems, these pointers may end up pointing to now-deleted assignments, or none at all.
The result is that the review harness may have extraneous assignments listed.

You'll first want to find the null assignment pointers. Use the Find radio buttons. Click Submit to access
a list of the assignment pointers.

To fix these, select the Fix radio buttons, and click Submit.

Change Work Class

This action allows you to change a work object's class (work type) to another class in the same work
pool.

Caution: if a flow executing on the work object, and that flow isn't defined on the new class, a flow
problem will occur.

Add To a cover

This action allows you to add a work object to a cover. If the work object is already associated with a
cover, it is removed from the current cover. Enter the work object ID.

Remove from a cover

This action allows you to remove a work object from its cover. If you are fixing a cover, enter the ID of
the work object that you wish to remove.

When fixing a work object, his action appears only if the task belongs to a cover.

Use the FlowProblem flow to route and fix common flow

problems
Summary
When an operator completes an assignment and a problem arises with the flow, this a Flow Problem.
The primary flow execution is paused and the standard Work- FlowProblem flow "takes over", for
service by an administrator.

This article provides a guide as to what should be done with such assignments.

Suggested Approach
The flow results in an assignment routed to the Flow Problem Operator. This should be a user with the
role of system administrator.

To set the user to whom flow problem tasks are sent (routing and notification), override activity Work-
.getFlowProblemOperator.

The flow operator can select two actions:

Return to (fixed) problem flow

Cancel this assignment

Analyze the problem using the information in this article. If the original flow can proceed, select the first
action. When selecting the option "Return to (fixed) problem flow", you can can specify a new action to
take in place of one that caused the problem .

If the problem can't be fixed, the select the Cancel action. This deletes the Flow Problem assignment.

The administrator can then open the FixWork flow to run some additional utilities on it. See How to use
the FixWork flow to repair flow and assignment problems.

Routing Problem

"The routing activity had the following problem: ..."

a. Review the routing activity. Verify that all the properties are set, and all the expected parameters
have been passed to it. If the activity uses a decision rule, verify that all the inputs and outputs
are valid.
b. Does the operator ID instance exist? Was it deleted? While Process Commander does not always
require that an assignee exists, the routing activity can call additional functions based on the
assigned operator. Verify that it catches "Record Not Found" exceptions.

Once the underlying problem has been fixed, the FlowProblems assignment can be completed.

Flow Stuck Problem

"The flow is stuck - none of the connectors from step X taken. No connector with status Y found."

a. The flow rule may have been revised so that X no longer leads to flow action Y .
b. Two users/processes update the same work object without synchronizing -- in other words, two
 people are working on the same work object without talking to each other. Normally, Process
Commander uses locking to enforce synchronization. In rare situations, lock checking may be
incomplete of circumvented.

Troubleshooting
FAQ: Why does Visio 2007 always open in an external
application window and not within the Flow Editor?
Question

A developer asks: Why does Microsoft Visio 2007 open in an external application window and not in the
Process Commander Flow Editor?

After creating a flow rule, when I click the Flow Editor icon to open Visio within Process Commander,
the Flow Editor toolbar does not appear. I cannot perform Save, Save As, Add to Favorites, and other
actions.

Answer
Visio 2007 does not open in the Internet Explorer browser session because Microsoft Office 2007 sets
the BrowserFlags registry value for all products of the suite to open file types within the appropriate
Microsoft Office application and not within an Internet Explorer session.

Caution: The following procedure instructs you to edit the Microsoft Windows registry. Be very careful
when editing the registry. Editing mistakes in the registry can cause irreversible damage because the
registry contains the settings for the operating system and application components. Refer to the
Registry topic cited in the Microsoft References below for more information.

To enable Visio 2007 to open in the Process Commander Flow Editor, complete the following steps:

1. Make a backup copy of your Microsoft Windows registry. Refer to the Microsoft Support article
cited below if necessary.
2. To open the Registry Editor, from the Start menu on your Windows desktop, click Run. In the
Open field, type regedit and click OK.

Alternative: Open a command window. In the command line, change to the WIndows directory path
and type the command regedit.exe.

3. In the Registry Editor, go to \HKEY_Classes_ROOT\VisioDrawing.11 and delete the entry

BrowserFlags.
Additional Information
About Flow rules

Microsoft References
A new window opens when you try to view a 2007 Microsoft Office program document in Windows
Internet Explorer 7 or Internet Explorer 8

Registry

How to back up and restore the registry in Windows XP

Editing the Registry Hive For Your Image on the Target Device

Issue: Unable to Save a Flow due to use of reserved word in

the name
Symptom
Flows are the fundamental rules that represent business processes. They determine:

The person or persons who work on a work object

The sequence in which the persons work on the object.

The decisions and processing that automatically occur on the work object.

When creating flows or sub-flows (flows called from the main flow) ensure you are using a unique name.
For example, if you name a flow using a reserved name, an exception error similar to the following
occurs:

** Java generation failed: Exception thrown by

"com.pegarules.generated.pega_procom_flowfua.flowMethodBody

Naming a flow ErrroHandler is an example of using a reserved name as a flow name. ErrorHandler is a
reserved name in Process Commander used to handle specific errors and exceptions.

Solution
If you have given a flow or sub-flow a non-unique name, you must use the Flow Explorer to locate and
rename the flows and sub-flows. Access the Flow Explorer in one of the following manners:

From the Developer portal Home page:

1. Click to access the Process slice.

2. Choose Explorer in the drop-down list.

The group labeled Processes for the XX Application includes the Flow Explorer display, where XX is
the current work pool name.

From the Flow Rule form:

1. Click the Related Rules toolbar button to display a drop-down menu.

2. Select Flow Explorer for flow from the menu.
3. The Flow Explorer appears with the selected flow as the starting point.

Troubleshooting: "Error: Flow Not At Task" with incorrect use

of WriteNow parameter in Obj-Save method
Summary
When selecting a work object from the worklist, you receive the following error message:
The flow this assignment corresponds to is no longer at this task.

To avoid this situation, check for common conditions that can cause this problem. Explicitly restarting
the flow at a specific assignment will allow processing of the work object to resume.

Explanation
A work object can have multiple assignments, which Process Commander synchronizes. Occasionally,
this synchronization of the work object and its assignments can be broken.

Here are the most common causes of a missing flow triggered by a break in the synchronization of the
work object and an assignment:

The application includes an activity that calls the Obj-Save method with the WriteNow parameter
set inside of the process flow.

This is a misuse of the WriteNow parameter. If the enclosing transaction then fails for
some reason, the object that was saved is now out of synch with the work object.
Deselect the WriteNow parameter if it is checked in the Obj-Save method of an activity
inside a process flow.

An explicit Commit is added to a rule during the processing of a transaction.

The Service Level Agreement (SLA) agent may be trying to process the assignment, which is
locked by you or another user. If advanced lock management is turned on, set the Lock Retries to
zero (0) for SLA rules.
A corresponding flow on a work object is at a different task. That is, pxTaskName on assignment
and pyLastFlowStep in the pxFlow page differ because any of the following conditions exist:
The Assignment saved the WriteNow parameter while the work object was being processed.
The work object was reopened from the database and saved.
The work object saved the WriteNow parameter, triggering an error that causes the
transaction to roll back.

Suggested Approach
To restart the flow at an assignment, create an activity that uses Work-.RetryProblemFlow to restart the
flow and recreate the assignment:

1. Create an activity (for example, FixProblemFlow) with the following steps:

1. Call the method Obj-Open-By-Handle with the pzInsKey of the work object you want to open.
2. Call the standard activity Work-.RetryProblemFlow.
This activity needs two parameters, FlowName and FlowStep:
​FlowName is the name of the flow you would like to start.
FlowStep is the step from where you would like the flow to run.
​For example, if you have a problem with an assignment on the flow, you may want to
restart the flow from the step above the assignment so the assignment can be re-
processed. If you are not sure how to get the Flow step name, you can find it by viewing
the Generated Java Code.
3. Once you have these two values, pass them as parameters to the activity Work-
.RetryProblemFlow.
4. Call the method Obj-Save.
2. Run the activity.

You can now open the work object without an error.

Additional Information
When to set the WriteNow parameter in the Obj-Save and Obj-Delete methods

Related GCS Case Object Number

KR-255, SR-71907

Troubleshooting: "Error: Flow Not at Task" and service level

goals in the past
Symptom
A developer asks: For two distinct assignments, our system contains assignment objects that are never
deleted. The user can proceed normally through the flow, however a 'stale' assignment remains on
their worklist. When they click the assignment, an error appears

Error: Flow Not At Task

This error only occurs only at two of the many assignments in our flows. However there is very little
about these assignments that is out of the ordinary. Also, the audit trail entry shows that the
assignment has been completed. We also see the goal time was reached on this 'stale' assignment.

After more analysis, we found that when we turn off the Pega-ProCom agent during our stress test,
these errors do not occur. We think the Pega-ProCom agent and the user have a locking/committing
issue.

By the way, 80+% of assignments have goal times that are in the past even when they are first set, and
so run instantly.

Solution
If goal times are in the past when first set, the behavior you describe is expected,.

The reason is that the Pega-ProCom agent:

1. Runs periodically and detects the goal time event

2. Is unable to lock the work object as it is locked by a user
3. Saves the assignment and decrements the Lock Retries.

That can lead to the problems you report if the agent is never able to delete the assignment.

As a workaround, set the Lock Retries to zero in the service level rules.

Troubleshooting: "Save failed: A commit cannot be

performed"
Symptom
A developer reports: I am getting an error. How can I get around it?

** Save failed: A commit cannot be performed because a deferred save of an instance of class
Subscribe-CustServ-GCSReports failed: code:
SQLState:
Message:

I've checked the WriteNow parameter on the Obj-Save method to ensure that correspondence we send
includes the most recent work object data (rather than stale work object data.)

Solution
Using Write Now — also called "Save immediate" — can case data integrity issues that cause such
errors. You need to find a way to avoid using the Save immediate processing.

For example, when you first create a work object , you don't have a lock on it , so if you write it to the
database using Save-immediate, somebody else can acquire the object and start modifying it.

As a best practice, restructure your activities to eliminate use of Save immediate, not because V4.2SP3
forces you to, but to avoid such possible data integrity issues.

In flows, leave such transaction handling to underlying flow code. You need not make transaction
boundaries in your own activities that are called by flows. Process Commander validates utility activities
called by the flow and validation fails if there is use of Save immediate.

You need not use Save Immediate to address your concern about correspondence having stale work
object data. Correspondence will never contain stale data if your flow processing finishes the transaction
boundary.

Transaction boundaries in the flow are at:

the flow start shape

each assignment shape
FlowEnd shape
If your application sends out stale data in correspondence, it means that you have to examine the
transaction boundaries, avoid Obj-Save transaction handling, and convert to using only flow-rule-
controlled transaction handling.

See locking details in Understanding V4.2 advanced lock management.

Related topics

Understanding V4.2 advanced lock management.

Troubleshooting: Blank window when starting Visio (Windows

XP SP2)
Symptom
When Process Commander developers run Windows XP SP2 on their workstations, they may see a blank
screen when they try to launch Visio, followed by a popup window labeled "Microsoft Internet Explorer"
which displays:

There was a problem switching to "Flow Edit" mode. Restore the "Form View" mode?

Solution

Explanation

These errors are due to Windows XP Service Pack 2. SP2 significantly tightened Internet security, which
creates a number of issues for Process Commander Version 4.2.

To support a rich user interface experience, Process Commander uses ActiveX components. Process
Commander also employs VBA macros in Excel Import manager and Visio editor content. These client
components conduct HTTP communications with the Process Commander server. XP SP2 changes some
behaviors in accessing results on HTTP requests, resulting in error conditions.

Additionally, under XP SP2, applications cannot be embedded into an HTML frame if this causes cross-
domain security violations. The V4.2 implementation launches a Visio session from a local Visio
document (located in a temp folder) and tries to embed it into a remote server-based HTML frame,
again causing errors.

Resolution

Update: V4.2 Service Pack 2 (SmartBuild) fixes these issues.

Troubleshooting: Call Super Class Model

Summary
A developer asks: Why is the Call superclass model option on the Model form not working at runtime?

The application includes a model pyDefault in the class Work-Application-Mortgage with the Call
superclass model checkbox option selected..

There is also a model with this name in the class Work-.

Next, a model is added to the class Work-Application-.

The class Work- is the parent of Work-Application-. The class Work-Application- is the parent of Work-
Application-Mortgage. However, when the Work-Application-Mortgage.pyDefault rule executes, the
Work-Application- model is ignored.
Suggested Approach
After you save the Work-Application- model, you must also resave the model in the class Work-
Application-Mortgage.

Once saved, the Work-Application- model property settings become available to the Work-Application-
Mortgage model.

Process Commander identifies the superclass to be called at the time you save the Model rule form, not
at runtime.

Troubleshooting: Cannot open or edit older, migrated flows

If your application includes flows created in older PRPC releases that have been migrated to newer
releases, some of the rule forms of these old flows may not load in the Designer Studio of the newer
PRPC release. When you, the application developer, try to open the rule forms of these older flows, you
see a busy indicator showing Opening as the never-ending status, and no content loads in the rule form.
None of the form tabs, not even the History tab, loads content.

Checking the PegaRULES logs, you see the Java Null Pointer Exception (NPE) for Java Server Page (JSP)
execution.

Error in JSP execution

java.lang.NullPointerException

at com.pegarules.generated.html_section.ra_stream_pzruleformdiagram_<br />
...<br />
.property_Rule_Obj_Flow_pzOneViewerModelerErrorMaker<br />
(ra_stream_pzruleformdiagram_<br />
​...

HFix-5328 for PRPC 6.2 SP1 and HFix-8368 for 6.2 SP2 correct this problem by introducing a new When
rule to skip code when a pyModelProcess property does not exist. After installing the hotfix appropriate
to the PRPC version you are using, you can open the forms of these older flow rules in the Designer
Studio of the newer PRPC release. However, when you try to edit and save these same flow rules, you
get the following error:

**Start shape must be connected to one or more shapes

Errors
First error
Error in JSP execution

java.lang.NullPointerException

at com.pegarules.generated.hasMessages_<br />
060201_NkIYplDb9nAuJCnpX0y43A.hasMessages06_02_01<br />
(hasMessages_060201_NkIYplDb9nAuJCnpX0y43A.java:110)

at com.pegarules.generated.hasMessages_<br />
060201_NkIYplDb9nAuJCnpX0y43A.invoke<br />
(hasMessages_060201_NkIYplDb9nAuJCnpX0y43A.java:84)

at com.pega.pegarules.generation.internal.library.LibraryRuntime.<br />
resolveAndinvokeFunctionViaReflection(LibraryRuntime.java:131)

at com.pega.pegarules.generation.internal.library.LibraryRuntime.<br />
invokeLibraryRuntime(LibraryRuntime.java:108)

at com.pega.pegarules.session.internal.mgmt.Executable.<br />
invokeLibraryRuntime(Executable.java:7894)

at com.pega.pegarules.priv.generator.LibrarySupport.<br />
resolveAndInvokeFunctionViaReflection(LibrarySupport.java:181)

at com.pegarules.generated.pega_rules_default.<br />
hasMessages(pega_rules_default.java:2401)
at com.pegarules.generated.html_section.<br />
ra_stream_pzruleformdiagram_b26cff87a873175bbf9929c6b04dbcd6<br />
.when_2(ra_stream_pzruleformdiagram_<br />
b26cff87a873175bbf9929c6b04dbcd6.java:405)

at com.pegarules.generated.html_section.<br />
ra_stream_pzruleformdiagram_b26cff87a873175bbf9929c6b04dbcd6<br />
.property_Rule_Obj_Flow_pzOneViewerModelerErrorMaker<br />
(ra_stream_pzruleformdiagram_b26cff87a873175bbf9929c6b04dbcd6.java:457)

Second error
**Start shape must be connected to one or more shapes

Explanation
The first error and issue are caused by older flow rules using a property called pyTaskInfo. If you
migrate these older flows to a newer version of PRPC, the flows do not include the property
pyModelProcess. HFix-5328 (PRPC 6.2 SP1) and HFix-8368 (PRPC 6.2 SP2) correct this issue and allow
you to open the rule forms of older flows.

The second error and issue highlight that the missing pyModelProcess property is still a problem
because you cannot edit and save the older flow rules. You must convert these older flows into the
more modern Process Modeler flows.

Suggested approach
To convert older flow rules to newer Process Modeler flows, follow these steps:

1. Verify that your PRPC system has HFix-5328 for PRPC 6.2 SP1 or HFix-8368 for PRPC 6.2 SP2
installed:
Run the Update Manager System Scanner to check the inventory of installed hotfixes installed.
With the appropriate hotfix installed, you should be able to open the rule forms of older flows.
2. Save the activity Rule-Obj-Flow * OpenDefaults in your ruleset.
3. To this activity add Step 2, the method Call BPMConvertTaskIntoModel.
4. Specify the precondition @(Pega-RULES:Default).PageExists(.pyModelProcess").
5. Leave the rest of the activity as it is.

6. Open an affected flow and click View > Modeler to convert the flow to Process Modeler.

7. Confirm that the Process Modeler shapes now display for the flow.
You should now be able to edit and save the older flow rules.

Troubleshooting: Corrupt Visio diagram when flows created

with Application Accelerator use non-English Regional
Settings
Summary
You can encounter Visio diagram problems when you try to open flow rules created by the Application
Accelerator if your client workstation's operating system is set for a non-English language locale. Most
notably, flow diagram shapes are not visible under a semi-transparent blue overlay masking the Visio
screen.

These flow editor (Visio diagram) problems have been reported for Process Commander v6.1 SP2
running in non-English locales on Windows 7 64-bit, Apache Tomcat, IE8, and Visio 2007 SP2. You might
also encounter the problems using Process Commander v5.5 SP1 in non-English locales.

The Suggested Approach describes the local change that you can make until a hotfix or correction in a
future release of Process Commander is available.

Details
For flows generated by default using the Application Accelerator, you will encounter corruption of the
flow diagram in Visio if the operating system for your client machine specifies a non-English language
locale, specifically a non-English number format.

Non-English language locales use the period (.) as the thousand separator and the comma (,)
as the decimal separator, for example, 123.456.789,00.
English language locales use the comma (,) as the thousand separator and the period (.) as
the decimal separator, for example, 123,456,789.00.

When you open Visio to edit an Application Accelerator-generated flow, the blue overlay
masking the screen makes the flow diagram unusable.
Suggested Approach
1. Resolve your Visio diagram issues for the scenario described by temporarily changing the Regional
and Language Options for your client machine to any English locale.

1. Find the Regional and Language Options on the Control Panel. Make sure that the number setting
displays this format: 123,456,789.00
2. Save the diagram with the English setting applied. The diagram renders correctly.
3. Restore your original non-English setting to continue editing the flow with correct diagram display
and your correct regional setting.

Troubleshooting: Error:Assign Mismatch" when a Before This

Action activity transfers a work object
Symptom
A developer asks: We have an application that sometimes requires that a work object is reassigned to
the current operator after it is updated by him. These work objects are often selected from a
workbasket.

Our application was configured to update the assignment related to this work object in the Before this
action activity of many local flow actions. These activities start when the user selects the associated
action in the action drop-down list. Note that this means the activity run without the user clicking
Submit on any of the forms.

This is causing many assignment errors to appear in the workbaskets where the object was originally
assigned. The instructions become:

Error: Assign Mismatch

We are using the Work-.Reassign activity. This activity attempts to remove the work basket assignment
(using the Obj-Delete method on the Assign-WorkBasket object) and create a new worklist assignment
(Obj-Save method on the Assign-Worklist object).

Solution

Explanation

Relationships between assignments and work objects are bidirectional. The assignment holds a
reference to the work object. The work object holds references to all existing assignments (under the
.pxFlow Page Group).

Updates to assignments from the Before this action activity of a flow action are unwise. In the case of
the scenario described, the assignment updates were being rolled back at this point. The problem is
that the updates to the work object were not being rolled back, resulting in the data inconsistency and
the Error: Assign Mismatch message.

Workaround

Do not reassign the work object before a user has performed any action on it. Defer updates to
assignments until after the actions have been performed by the user, . as part of the After this action
activity call. That way, the updates are fired when the user submits the local flow actions.

To address your business requirements, move the reassignment of the work objects to the After this
action activity. All transfers of assignments will occur correctly and no assignment errors will occur .

Troubleshooting: Flow diagram in developer portal is stale

Symptom
A developer asks:

I made changes to my flow rules and successfully saved them.

Still, the flow on the dashboard of my portal hasn't changed, and the newly changed Short Descriptions
for the flows don't appear in the New work select-list. The display is stale.

Solution
Your changes are saved and are operational.

You are not seeing them because cached versions exist on your client workstation.

For performance reasons, Process Commander performs extensive caching. Refresh buttons are
available at several locations where they're most likely to be needed.

For this case, use the Refresh Process link just to the right of the flow image on the Dashboard.

Troubleshooting: Improve performance of SLA Agents

running on multiple nodes (Oracle)
Summary
This article applies to PRPC V5.5 SP1 (HFix-3536). The same correction is available for PRPC V6.1 SP2 in
HFix-4127, as indicated in the Suggested Approach.

Administrators of PRPC systems that were upgraded from V5.1 to V5.5 SP1 report that work objects with
Service Level Agreements (SLAs) are not processed in a timely manner, causing a backup of work
queues. The problem was reported for systems using the Oracle database management system
configured in a clustered environment (multiple nodes). HFix-3536 for PRPC 5.5 SP1 (or HFix-4127 for
PRPC 6.1 SP2) corrects the processing of work objects using SLA agents to prevent the work queue from
backing up.

The hotfix delivers an SQL script that creates the new stored procedure for the Oracle database
management system: schemaFiles/schema/oracledate/proc/sppr_sys_reservequeueitem_b.sql

Problem Scenario
The system adds approximately 10,000 SLA queue records to the queue table for normal end-of-day
assignment processing. It takes an excessively long time (four and a half hours) for PRPC to complete
the processing of these records. Investigation of the SLA events across all nodes on which SLA agents
are running indicates that the SLA agents are not processing 500 records at a time as expected because
the Select query in the stored procedure sppr_sys_reservequeueitem_b is malfunctioning. SLA agents
are not processing the maximum quota of records.

Hotfix Details
HFix-3536 and HFix-4127 modify the stored procedure sppr_sys_reservequeueitem_b so that the Select
query gets ten (10) keys at a time and attempts to lock the work object for the current agent from the
top. Any given key in these ten (10) keys will be in one of three states:

1. The key is present and not locked. The work object is processed.
2. The key is present, but locked by another user. The work object is skipped and the key for the next
work object in queue is processed.
3. The key no longer exists. Another process reserved the work object, processed it, and deleted its
key.

Therefore, if the top-most key cannot be locked for this agent because of States 2 and 3, the stored
procedure will try to lock the next item.

Suggested Approach
You cannot use Update Manager to install either HFix-3536 or HFix-4127.

1. Contact Pegasystems Global Customer Support (GCS) and ask for HFix-3536 for PRPC 5.5 SP1 or
HFix-4127 for PRPC 6.1 SP2.
2. Stop the application server.
3. Drop sppr_sys_reservequeueitem_b stored procedure connecting to the database using database
tools.
4. Run the script file delivered in the hotfix attachment to create the new version of the stored
procedure: schemaFiles/schema/oracledate/proc/sppr_sys_reservequeueitem_b.sql
5. Start the application server.

Troubleshooting: Internet Explorer 6 terminates

unexpectedly in Developer portal
Symptom
Internet Explorer 6.0 unexpectedly terminates when you are using the Developer portal. Upon
termination, IE displays the following message:

Internet Explorer has encountered a problem and needs to close. We are sorry for the inconvenience.

When you log in to Process Commander again, you might notice loss of data caused by the termination
of the browser.

Internet Explorer 6.0 might terminate unexpectedly under the following circumstances:

While editing a flow rule in the Flow Editor, you click a flow shape to select it; then you right-click
to display the options menu.
If you are using the Developer portal menus, you click to display the menu drop-down list; then you
click a different top-level menu option without making a selection from the original menu option.

These are two examples of when IE termination might occur. You also might encounter this problem in
other scenarios.

Solution
The IE 6.0 termination is caused by the presence of Microsoft Security Update KB918899 (MS06-042),
Cumulative Update for Internet Explorer for Windows XP Service Pack 2.

You must uninstall this update to resolve this issue:

1. Select Start > Control Panel to display the Control Panel window.
2. Open the Add or Remove Programs window.
NOTE: Ensure that the Show Updates checkbox at the top of the window is selected. This allows
you to view all the Microsoft updates installed on your machine.
3. Scroll down until you see the following entry:
Security Update for Windows XP (KB918899)
4. Select this entry and click Remove.
5. When the system finishes removing the update, close the Add or Remove Programs window and
the Control Panel.

You can now start Process Commander again and work without interruption from unexpected IE
termination.

Known problems with Microsoft Security Update KB918899 (MS06-042) led to the issuance of more
recent security updates. Ensure that your computer is set to receive notification of Microsoft Windows
Security Updates that are appropriate for your version of Microsoft Windows.

References

Article ID: 918899, MS06-042: Cumulative security update for Internet Explorer

Microsoft Download Center, Windows Security & Updates

Troubleshooting: LockGoneException Save, Delete, or

Commit fails during bulk processing (HFix-8511, Oracle)
Your application calls the activity pzBulkProcessItems to assign multiple work objects to users. In almost
every instance, the bulk processing of work assignments to users results in the lock on the work object
being lost. The LockGoneException error is displayed.

To add detailed lock manager information to the Pega log, set the Logging Level Settings tool with this
category to Debug: com.pega.pegarules.engine.database.LockManagerImpl.

The symptoms seem to match those observed when the Pega configuration parameter commitNoWait is
used. This prconfig setting affects how Oracle treats commits.

Install HFix-8511 if your DEBUG logging of LockManagerImpl shows precisely the lost lock conditions
shown in the example.

Error
com.pega.pegarules.pub.database.LockGoneException: Save, Delete or Commit has failed because lock "<work record name>" is not held.

Explanation
The Pega-provided commitNoWait parameter affects how Oracle treats commits for the single
Transaction in flight. Independent of this setting, it is possible to configure Oracle using a global setting
to have this same behavior on every Transaction.

The following commands alter COMMIT behavior on a global basis:

ALTER [SYSTEM | SESSION] SET COMMIT_WRITE='WAIT';

ALTER [SYSTEM | SESSION] SET COMMIT_WRITE='NOWAIT';

ALTER [SYSTEM | SESSION] SET COMMIT_WRITE='IMMEDIATE';

ALTER [SYSTEM | SESSION] SET COMMIT_WRITE='BATCH';

ALTER [SYSTEM | SESSION] SET COMMIT_WRITE='BATCH,WAIT';

ALTER [SYSTEM | SESSION] SET COMMIT_WRITE='BATCH,NOWAIT';

ALTER [SYSTEM | SESSION] SET COMMIT_WRITE='IMMEDIATE,WAIT';

ALTER [SYSTEM | SESSION] SET COMMIT_WRITE='IMMEDIATE,NOWAIT';

The Oracle NOWAIT and BATCH parameters cause the commitNoWait behavior regardless of any PRPC
settings that are specified to the contrary.

Running the following query displays the global status, which indicates whether you have to modify the
behavior to prevent locking errors and possibly other errors:

select * from v$parameter where name like '%commit%'

Example
If you turn on DEBUG logging in the LockManagerImpl class, you can see that the system has locked the
work record, the record has not been unlocked, and, when you check the record again, the system does
not see the lock.

In this example log, the highlighted lines show that the lock should be held.

Follow the suggested approach for installing HFix-8511 only when your scenario matches this example.

2013-11-08 14:31:44,147 [WebContainer : 6] [ pyNS_CPMPortal0_HomeTab] [RulesetVersion ] (Internal.access.LockManagerImpl) DEBUG

<target> - Requestor <requestor> is attempting to lock "<work record name> "

2013-11-08 14:31:44,148 [WebContainer : 6] [pyNS_CPMPortal0_HomeTab] [RulesetVersion] (Internal.access.LockManagerImpl) DEBUG

<target> - Requestor <requestor> running following SQL to add lock "<work record name>": insert into pr_sys_locks (pxCreateDateTime,
pxCreateOpName, pxCreateOperator, pxCreateSystemID, pxExpireDateTime, pxLockHandle, pxObjClass, pxOwnerId, pxSystemName,
pxSystemNode, pxUpdateDateTime, pxUpdateOpName, pxUpdateOperator, pxUpdateSystemID, pxUserHost, pyLabel, pzInsKey) values (?, ?, ?,
?, ?, ?, 'System-Locks', ?, ?, ?, ?, ?, ?, ?, ?, '', ?)

2013-11-08 14:31:44,154 [WebContainer : 6] [pyNS_CPMPortal0_HomeTab] [RulesetVersion] (Internal.access.LockManagerImpl) DEBUG

<target> - Obtained lock "<work record name> "

2013-11-08 14:31:44,173 [WebContainer : 6] [pyNS_CPMPortal0_HomeTab] [RulesetVersion] (Internal.access.LockManagerImpl) DEBUG

<target> - Requestor <requestor> verifying that it still holds lock "<work record name> "

2013-11-08 14:31:44,174 [WebContainer: 6] [pyNS_CPMPortal0_HomeTab] [RulesetVersion] (Internal.access.LockManagerImpl) DEBUG

<target> - Requestor <requestor> running following SQL to check for lock "<work record name>": select pxOwnerId as "pxOwnerId",
pxUpdateOperator as "pxUpdateOperator", pxUpdateOpName as "pxUpdateOpName", pxExpireDateTime as "pxExpireDateTime",
pxUpdateDateTime as "pxUpdateDateTime", pxLockHandle as "pxLockHandle", pxCreateDateTime as "pxCreateDateTime" from pr_sys_locks
where pzInsKey = ?

2013-11-08 14:31:44,177 [WebContainer : 6] [pyNS_CPMPortal0_HomeTab] [RulesetVersion] (Internal.access.LockManagerImpl) DEBUG

<target> - Requestor "<requestor> " found no lock on "<work record name>"

2013-11-08 14:31:44,178 [WebContainer : 6] [pyNS_CPMPortal0_HomeTab] [RulesetVersion] (Internal.access.LockManagerImpl) DEBUG

<target> - Requestor <requestor> does not hold lock "<work record name> "

2013-11-08 14:31:44,208 [WebContainer : 6] [pyNS_CPMPortal0_HomeTab] [RulesetVersion] (SCaseDeatils.CPM_Portal.Action) ERROR

<target> - obj-save failed.

After you install the hotfix and specify the lockmanager parameters in the prconfig.xml file, the new
functionality is triggered during bulk processing of work assignments. You see a message in the
PegaRules log file about the first attempt to obtain the lock. The message is displayed without your
having to increase the debugging level.

2013-12-11 14:01:18,439 [WebContainer : 14] [pyNS_CPMPortal0_HomeTab] [RulesetVersion] (Internal.access.LockManagerImpl) INFO <target>

- Attempt number 1 to obtain the lock.

If, after a delay cycle of one or more attempts, the lock is discovered, no further log entries or errors
occur.

Suggested approaches
Best practice
Upgrade to Pega 7.1.7 or a later release.

Alternative approach
If you are using PRPC 6.1 SP2, do the following steps:

1. Go to My Support Portal and create a Support Request to obtain HFix-8511.

2. Follow the instructions in the HFix ReadMe.txt file to install HFix-8511 and specify its required
settings.

PRPC 6.1 SP2 HFix-8511, Exception on backend while assigning WorkObject to users

HFix-8511 introduces new settings in the prconfig.xml file to allow a retry when the lock is not held
during a database COMMIT. The hotfix allows you to turn off the Oracle commitNoWait parameter by
customizing the wait time and the number of attempts to retrieve a lock.

For example, you can specify parameters that retrieve a lost lock for a work item after 100 milliseconds
and 10 attempts.

During a COMMIT (or a SAVE-IMMEDIATE), the system determines whether the required lock on the
object being committed is missing. If the lock is missing, the new code does the following actions:

1. Pauses for the specified number of milliseconds before looking again for the lock.
2. Retries the specified number of times before either seeing the lock and proceeding with the
COMMIT or throwing an exception with the LockGoneException message.

After you install HFix-8511, specify the following parameters in the prconfig.xml file:

lockmanager/numberOfRetryAttempts 10

lockmanager/configuredWaitTime 500 (milliseconds)

With these two values specified, the system waits up to five extra seconds before failing the COMMIT
because of the lost lock.

During investigation, additional logging in the log files revealed that the system was encountering the
LockGoneException quite frequently, entering the retry loop, and always successfully seeing the lock
after one wait interval of 0.5 seconds.

Related GCS Case Object Number

KR-1146, SR-98912

Troubleshooting: No Shape Properties settings panel appears

in Visio Flow Editor
Symptom
When you're attempting to edit a flow in Visio, the flow diagram and shapes palette display correctly,
but the Shape Properties settings panel does not appear .

The area instead displays an HTML error page (the generic "Internet Explorer cannot display the
webpage" message with no error number).

Solution

Workaround

The problem is caused by an outdated OCX control file (ActiveX). If you remove this outdated file, a
replacement is automatically downloaded and installed on the next login.

To make this replacement:

1. Log off..
2. Navigate to C:\Windows\Downloaded Program Files.
3. Remove the Visio control, prVisioInterface.EmVisioInterface. You can remove all PRPC control files (pr*) and
the most current versions will be downloaded

Next, verify that your Internet Explorer settings permit ActiveX controls to be downloaded and enabled
on your machine:

1. Open Internet Explorer. Choose Tools > Options. On the Security tab, select Local Intranet, and
 click Custom Level.
2. In the ActiveX controls and plug-ins section, verify that the radio buttons for these options are set
to Enable or Prompt:

Download Signed ActiveX Controls

Download Unsigned ActiveX Controls

Verify that the radio button for this option is set to Enable:

Run ActiveX controls and plugins

Click OK twice to close the Internet Options dialog.

The Visio Flow Editor’s Shape Properties settings box will display properly the next time you edit a flow
rule.

Troubleshooting: No flows appear in New Work gadget after

renaming a class that is a class group
Symptom

After renaming a class that is a class group (work pool), application users find that no starter flows
appear in the New Work gadget on the navigation panel of the WorkUser or WorkManager portal — the
work pool selector drop-down list is empty:

This is due to the need to perform additional steps

as well as manually renaming references to the old class in instances of three data classes:

Background
To rename a class, select Tools > Classes > Rename a Class. When you rename a class, the wizard
automatically changes references to the old class name to the new class names in every (unlocked)
RuleSet and every (unlocked) version. Each renamed rule belongs to the same RuleSet and Version as
the original rule.

References to the old class name (if any) in the following data class instances are not automatically
renamed:

Data-Admin-DB-ClassGroup
Data-Admin-DB-Table
Data-Admin-Operator-AccessGroup

Solution
To resolve the issue:

1. Stop the server.

2. Delete the all the files in the PRGenJava and PRGenclass directories, within the temporary directory
identified in the prconfig.xml file..
3. Delete the PegaRULES_Extract_Marker.txt file.
4. Restart the server.
 5. Manually rename the following class instances:

- Data-Admin-DB-ClassGroup
- Data-Admin-DB-Table

Rename these class instances as follows:

a. Access the form for the appropriate class instance you want to rename.
b. Click the Save As button.
c. Type the new class name in the Class Group ( field and click Save.
6. Update each Access Group that references the old class group to reference the new class group (in
the Work Pool array on the Access tab)

Troubleshooting: Page property in Status field of Assignment

shape in Process Modeler renders as text
Summary
In the Process Modeler you reference a Page property (for example, Pg1.Prop1) in the Work Status field
under the Status tab of the Assignment shape properties. However, at run time the value of the Status
field on the work object assignment shows the Page property rendered as a literal string (for example,
Pg1.Prop1), rather than the value of the property from the clipboard.

Explanation
Versions of the Process Modeler included in PRPC 6.2 (when it was first introduced) through PRPC 6.3
SP1 do not evaluate property references added to the Work Status field under the Status tab of the
Assignment shape.

Suggested Approach
Starting with PRPC 7.1, property references added to the Work Status field under the Status tab of the
Assignment shape will evaluate properly to return the value of the property from the clipboard.

If you are running the Process Modeler in PRPC releases from 6.2 through 6.3 SP1, you can use one of
the suggested options below to resolve this issue.

Option 1
The simplest approach is to use a Utility shape before you arrive at the Assignment. The Utility calls the
standard out-of-the-box UpdateStatus activity, where you can pass the property reference as a
parameter.

Option 2
1. Save the UpdateStatus activity into an open ruleset version.
2. Add a step after Step 5 of the UpdateStatus activity.

3. Copy the below Java and paste it into the newly created Java Step (now Step 6).
​String status = tools.getParamValue("StatusWork");<br />
if(status.contains(".")){<br />
status = myStepPage.getString(status);<br />
myStepPage.putString("pyStatusWork",status);<br />
}<br />
else{<br />
OriginalStatus = myStepPage.getString("pyStatusWork");<br />
myStepPage.putString("pyStatusWork",status);<br />
}

4. Comment out Step 7.

5. Save the modified UpdateStatus activity.

The Page property reference (for example, Pg1.Prop1) that you added to the Work Status field under the
Status tab of the Assignment shape properties will now appropriately return the value of the property
from the clipboard.

Additional Information
Flow form - Process Modeler - Editing Assignment shapes

Flow form - Editing in Process Modeler - Utility shape

Troubleshooting: Process Modeler flow shape images not

rendering
Summary
On a Flow form, you select the Diagram tab to edit a flow in PRPC’s Process Modeler flow editor;
however, the shapes and connectors for your flow diagram are not displayed on the screen. Not all
developers in your organization are experiencing this issue.

Examples
Incorrect Rendering of a Flow in Process Modeler

Correct Rendering of a Flow in Process Modeler

Explanation
This issue can occur if the ActiveX controls and plug-ins setting for Binary and script behaviors is
set to Disable within your Microsoft Internet Explorer 9 browser Security settings for the Local Intranet
zone. PRPC’s Process Modeler flow editor requires that the Binary and script behaviors setting be set to
Enable.

It is possible that just this setting was changed, or it could be the result of someone changing the
Security settings for the Local Intranet zone from the default of Medium-low to High.

Suggested Approach
In some cases, browser security settings may be tightened temporarily to mitigate the risks associated
with a new and publicly disclosed vulnerability in Internet Explorer (IE). Prior to following the steps
below to change your browser security settings, check with your Information Technology (IT)
department to ensure that you have the most up-to-date IE security updates installed.

How to enable Binary and Script Behaviors in IE 9

1. Open Internet Explorer.
2. Click the Tools menu, then click Internet Options.
3. On the Security tab, click the Local intranet icon, then the Custom level button.
4. Scroll down the Security Settings list until you see ActiveX controls and plug-ins.
5. For Binary and script behaviors, click Enable.
6. Click OK, then click OK again.

PRPC’s Process Modeler flow editor will now correctly render the shapes and connectors for your flow
diagram.

Additional Information
Introducing Process Modeler, an alternative to Visio for creating and editing flows

Troubleshooting: Visio "Compile error..." message and

MSMXL.DLL version
Symptom
You try to open a flow for editing, and you receive a compile error::

Solution
Workaround
Check that you have a supported version of msxml.dll in your C:/Windows/System32 directory. The msxml.dll
version 1.0 - 2.5 SP3 is no longer supported by Microsoft. The supported versions are msxml3.dll and
higher.

Related topics
The following Microsoft Knowledge base article describes how to port to supported versions msxml3.dll
or higher versions:

http://support.microsoft.com/default.aspx?scid=kb;en-us;823417

Troubleshooting: Visio 2002/2003 compatibility issues

Issue
A compatibility issue exists between flows saved in Visio 2002 and flows saved with Visio 2003. Flow
rules created and saved in Visio 2003 are not backward-compatible and cannot be opened in Visio 2002

If your system includes flow rules saved in Visio 2003 but some developers have only Visio 2002, a
workaround procedure is available..

Resolution
If a flow rule is created and saved in Visio 2003, and then later is opened, changed, and saved again in
Visio 2003, no problems occur. However, for both types of flows (External or Embedded) that are saved
in Visio 2003, if a user with Visio 2002 tries to open those flow rules, the following message appears:

This flow was last saved with Visio 2003. It cannot be edited in Visio 2002.

If your development team uses both Visio 2003 and Visio 2002 to edit flows, then when saving flows in
Visio 2003m select the Visio 2002 Format choice:

1. Open the Flow form, and click the Explore tab.

2. Click the Edit Flow External button.

3. When Visio starts, click the Visio Tools > Options menu item:
 4. Click the Save tab. In the Default Format box, select the drop-down box for Save Visio Files
as. Choose Visio 2002 Document . Click OK.
5. Make a small change to the document (moving a shape a small distance, for example). Save the
Visio document.
6. During the Save process, a Save Options box will appear. Click Visio 2002 Format to save the
document in the Visio 2002 format.

Troubleshooting: Visio flow editing and the IE Internet Zone

Symptom
Visio flow editing is not possible when Process Commander is accessed from the Internet Explorer Internet
zone, until you enable additional Internet Explorer security settings.

Explanation
Process Commander uses ActiveX controls to provide a rich experience for developers. For these
controls to seamlessly integrate with applications like Microsoft Visio 2003 (for flow editing), Internet
Explorer must grant these controls more access to the client workstation than is typically allowed for
external, World Wide Web sites.

For most internal sites, where the hostname is a single word identifier, Internet Explorer classifies the
site as belong to a Local intranet, and allows ActiveX controls to run with greater permissions. This
designation appears in small type at the bottom right of the browser window:

http://pegarulesserver:8080/prweb/PRServlet
However, if the URL reference to a server is further qualified with a domain, or the IP address is used,
Internet Explorer assumes that Process Commander is hosted by an external Internet site (whether or
not the address is actually external), and runs the ActiveX controls with far more restrictions. Examples:

http:// 192.168.0.13 :8080/prweb/PRServlet

http:// pegarulesserver.example.com :8080/prweb/PRServlet

With this URL setup, Visio errors may occur. When you click the Edit Flow External button in the Explore
tab of the Flow definition to open a flow in Visio (or just double-click the Flow form to open Visio), the
flow may take a long time to appear. In addition, the following error may appear:

There was a problem switching to 'Flow-edit' mode. Restore to 'Form-view' mode.

This error occurs because Internet Explorer switches to "external environment" mode.

Solution
In order to use Process Commander ActiveX controls with an IP address or a domain-qualified URL, you
must add that address of the Process Commander server to the list of Trusted Sites on each client
workstation.

The procedure below uses an IP address; the steps are the same for a domain-qualified URL.

1. Select the Internet Explorer Tools> Options menu.

2. In the Internet Options window, click the Security tab.

3. Click the Trusted sites icon.

Click the Sites button to add the IP address to the list.

4. Enter the appropriate IP address into the Trusted sites box, and click Add.The site is now one of the
Trusted web sites.

If your Process Commander server does not use secure HTTP — the URL starts with "http" not "https" —
clear the box next to Require server verification (https:) for all sites in this zone.
5. Click OK , and then click OK on the next form to save the changes.

Troubleshooting: Visio shapes stencil is frozen in middle of

every flow diagram
Symptom
A developer reports: Visio Professional is installed, and when I open a flow rule, the shapes stencil
appears in the middle of the window. I can't get rid of the stencil. I can't even move it.

Even after exiting from Process Commander, the next time I open Visio through Process Commander,
the shapes stencil remains stuck in the middle of the screen.

If I open Visio in standalone mode, it works fine. How do I get Visio to work with my flow rules?

Solution
Visio writes a temporary file on your local drive that records the positioning of the shapes stencil
window.

When Visio starts again, it remembers the size and position of the shapes window and the window is
frozen.

To fix this issue, you need to find and delete the temporary file.

1. Search for the file in the C:\documents and settings directory tree using an extension of ".vst". Look for
 files that have been updated in the last few days or when the problem first started.
2. Rename the file, then restart Visio to see if the issue is solved. If the issue reoccurs, then you
picked the wrong VST file. Rename the VST file back to its original name, and try another VST file.
3. Repeat until you rename the relevant file and clear the stencil from appearing.

Troubleshooting: Work Object ID duplicates

Summary
A developer asks:

If I have a work type that in an application that has work objects created both by users from the portal
and from an (unauthenticated) SOAP Service the two entry techniques should have separate work
object counters.

But if I create 3 work objects from the portal, the are numbered W-1, W-2 and W-3. But then when I
create the first one using the SOAP service, W-1 gets created, overwriting the W-1 created by
interactive users.

This happens because the requestor of the SOAP service is unauthenticated, so it doesn't belong to any
organization.

Is this the expected behavior?

Should we make the SOAP-created work objects have a different work object prefix than the
interactively-created work objects?
Or can I set an organization for an unauthenticated SOAP service?

Suggested Approach
To avoid this collision of work object IDs, use a single Organization data instance for both the BATCH
requestor and for the interactive requestors, or use two organizations and two work pools.

Unauthenticated requestors do not have an organization. You can specify an Organization instance for a
BATCH requestor if the BATCH requestor is authenticated. Set the Organization in an activity that
executes after logon.

Alternatively, if you decide to use two separate organizations, you'll need to follow SmartBuild best
practices, by placing them in separate work pools to avoid such work object ID issues. But if you decide
to use one organization, then one work pool is sufficient.

Troubleshooting: ‘Fail to compile generated Java’ for flows in

Draft mode on production system
Summary
After deploying an application to the production system, you see flow errors on screen and in the log
file.

Failed to compile generated Java

FirstUseAssemblerException

These errors did not appear when you tested the flow in the pre-production environments; for example,
process modeling, development, test, and staging. If you get these errors when trying to run a flow in
the production system, check to see if the flow is in Draft mode. Turn off Draft mode, save the flow rule,
and redeploy the application in the production system.

Errors
Errors appear on the screen and in the log file.

Error on screen when trying to run the flow

Failed to compile generated Java com.pegarules.generated.flow.sh_action_testflow_5b1ba71e70197c9af12735de6d1877b1: ---------- 1. ERROR in
com/pegarules/generated/flow/sh_action_testflow_5b1ba71e70197c9af12735de6d1877b1.java (at line 155) bIsConnector =
IsConnectorFlowAction_ASSIGNMENT63_circum0(strAction); ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The method
IsConnectorFlowAction_ASSIGNMENT63_circum0(String) is undefined for the type sh_action_testflow_5b1ba71e70197c9af12735de6d1877b1 ---
------- 1 problem (1 error)

Error in the log file when attempting to Revalidate and Save

2013-03-20 11:06:25,240 [ http-6221-1] [ Developer] [ TestApp:01.01.01] ( internal.cache.RACacheImpl) ERROR server|server.test.com
TestUser - Failed to generate com.pegarules.generated.flow.sh_action_testflow_5b1ba71e70197c9af12735de6d1877b1

com.pega.pegarules.pub.generator.FirstUseAssemblerException: Failed to compile generated Java

com.pegarules.generated.flow.sh_action_testflow_5b1ba71e70197c9af12735de6d1877b1: ----------

1. ERROR in com/pegarules/generated/flow/sh_action_testflow_5b1ba71e70197c9af12735de6d1877b1.java (at line 155)

bIsConnector = IsConnectorFlowAction_ASSIGNMENT63_circum0(strAction);

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The method IsConnectorFlowAction_ASSIGNMENT63_circum0(String) is undefined for the type

sh_action_testflow_5b1ba71e70197c9af12735de6d1877b1

----------

1 problem (1 error)

Explanation
Investigation of the flows with the error indicates that the flows are in Draft modepyDraftModeON=true.

The errors do not occur in the pre-production environments (process modeling, development, test,
staging) because you can save and run a flow in Draft mode in systems for which the production level is
set to a value less than 5. Rule resolution will find and process a flow rule when the flow is in Draft mode
and Rule Availability is set to Yes. This allows you to test the flow (including rule resolution) even
though some dependent rules do not yet exist. When flow Rule Availability is set to No/Draft, the flow
rule is not included in rule resolution.

Suggested Approach
For flows that cause the errors, turn off Draft mode, save the flow rule, and redeploy the application in
the production system.

Additional Information
Flow form -- Process Modeler Basics

Draft mode -- definition

How the system finds rules through rule resolution

Related GCS Case Object Number

KR-955, SR-77418, BUG-80555

Troubleshooting: Observed goal time interval does not match

the value in the service level rule
Summary
A developer asks: I have an service level goal that, after 58 seconds, calls the standard Work-.
ResumeFlow activity. As part of this, I increment a counter and update the work object history.

I have the Agent Queue instance of Pega-ProCom: Correspondence and SLA events for Assign- set to
Periodic, with an interval of 30 seconds.

However, when I look at the work object history, it appears that the goal is reached only every 2
minutes, not after 58 seconds.

What am I doing wrong?

Suggested Approach
You're not necessarily doing anything wrong.

However, you must factor in the 30 second wake-up interval, and with that the timing could work out to
as much as a minute and a half after you think the occurrence should take place. The timer does not
start until the agent completes, so that time it takes the agent to complete is being added to the total.

One very likely cause when you find service level timings very different from what you expect is a
difference between the database server time and the application server time. The query to see
whether an assignment is due compares the assignment goal or deadline time with the system date and
time. If the two machines clocks differ enough, you will see such service level timing discrepancies.

Verify the time synchronization between the database and application servers. Synchronizing the two
will likely clear up the timing interval discrepancies that you observe.

Archive: Case Management > Process

Archive candidates for Case Management > Process

Known Issues
Issue: Execute button is disabled during bulk processing
Symptom
A manager reports: When I perform bulk processing of assignments, the Execute button is unavailable,
grayed out. Yet, if I open an individual assignment, I can execute the ProcessAck feature. ProcessAck
is the only flow action for assignments in this workbasket.

What do I need to do to get the Execute button to be live? The tooltip hover text reads:

Either action has not been selected or operator security is insufficient.

This issue is resolved in V5.1+.

Solution

Workaround

Investigation shows that the behavior occurs only when exactly one flow action is connected to the
assignment. For assignments with multiple flow actions, the bulk processing Execute button is enabled
and operates correctly.

To work around the problem, add another flow action to the assignments in question so as to be able to
perform bulk processing on them.

Issue: SLA Agent not picking up items to process (Oracle)

Symptom

Service-level rules specify goals and deadlines that indicate the expected or targeted time to complete
an assignment or resolve a work object. When an assignment is created and service level rules apply,
Process Commander calculates the goal, deadline, and late times and stores those times with the
assignment.

When the standard ProcessServiceLevelEvents activity — part of the Pega-ProCom agent — runs, it
compares the current time to the goal, deadline, and late times of assignments to determine whether or
not they are late. This activity is sometimes called the Service-Level Agreement (SLA) agent.

The information on whether a work object is locked is stored in the pxExpireDateTime column of the
pr_sys_locks table.

In certain instances, when your PegaRULES database is hosted by Oracle , the activity does not pick up
expired work objects in pr_sys_locks even though the agent shows a successful state.

This issue is caused by incorrect SQL in the Browse tab of the following Rule-Connect-SQL rules for
Oracle:

SLAGoalAssignments
SLADeadlineAssignments
SLALateAssignments

Update: This issue is resolved in V5.3+.

Solution
The incorrect SQL code in the Browse tab is:

select pxLockHandle from pr_sys_locks where pxExpireDateTime <

{SLALateListPage.pxCreateDateTime DateTime}

In the above code, change the less-than character

<

to the greater-than character

>

--so the code appears as follows:

select pxLockHandle from pr_sys_locks where pxExpireDateTime >

{SLALateListPage.pxCreateDateTime DateTime}