Pega Platform 8.

8
7 April 2023

©2023 Pegasystems Inc

 Pega Platform 8.8 2

CONTENTS
Rules management___________________________________________________________________ 6
Creating rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Copying a rule or data instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Naming conventions for records. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Organizing rules into rulesets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Creating rulesets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Creating a ruleset and a ruleset version. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Configuring ruleset version settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Ruleset validation modes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Copying rulesets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Defining the security of a ruleset. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Categorizing a ruleset. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Deleting a ruleset. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
About the Ruleset Maintenance wizard. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Production rulesets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Organizing rules into classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Understanding class layers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Understanding class hierarchy and inheritance. . . . . . . . . . . . . . . . . . . . . . . . . 56
Understanding external classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Creating classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
General tab on the Class form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Locking tab on the Class form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Object locking. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Advanced tab on the Class form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
External Mapping tab on the Class form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Finding the class of a rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
About the Rename a Class wizard. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
About the Delete a Class wizard. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Rule resolution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

©2023 Pegasystems Inc

 Pega Platform 8.8 3

Ruleset list layers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Ruleset list usage during rule resolution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Viewing your application ruleset list. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Using pattern inheritance for rule resolution. . . . . . . . . . . . . . . . . . . . . . . . . . 119
Defining and changing the scope of rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Moving rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Setting rule status and availability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Troubleshooting final rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Troubleshooting blocked rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Extension points. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Creating a rule specialized by circumstance. . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Creating a circumstance template. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Creating a circumstance definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Date circumstance rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Circumstance rule examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Circumstance definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Date combinations and business requirements. . . . . . . . . . . . . . . . . . . . . 144
Controlling the order of circumstance definitions. . . . . . . . . . . . . . . . . . . . . 144
Redirected rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Base rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Finding rules by circumstance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Specializing a case type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Rule resolution exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Creating a rule specialized by a class or ruleset. . . . . . . . . . . . . . . . . . . . . . . . 153
Defining the input parameters of a rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Defining the pages and classes of a rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Rule skimming for higher ruleset versions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Adding a custom field. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Preparing for modifying rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Checking out a rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Standard rule checkout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Performing a private edit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

©2023 Pegasystems Inc

 Pega Platform 8.8 4

Checking out a rule to a branch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Viewing your checkouts and accessing bulk actions. . . . . . . . . . . . . . . . . . . 177
Rule checkout notes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Rule checkout tips. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Personal ruleset. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Checking in a rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Configuring the rule check-in approval process. . . . . . . . . . . . . . . . . . . . . 182
Rule check-in process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Checking in rules in bulk. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Restoring the earlier state of a rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Creating guidance for developers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Delegating a rule or data type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Delegating a data type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Rule and data type delegation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Prerequisites for delegating a rule or data type. . . . . . . . . . . . . . . . . . . . . . . 199
Best practices for delegating a rule or data type. . . . . . . . . . . . . . . . . . . . . . 199
Modifying a delegated record or data type. . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Configuring ruleset update behavior. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Deleting a rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Recovering a deleted rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Exploring rules in your application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Finding rules by type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Finding rules by class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Finding rules by name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Finding rules by dependency. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Finding rules by custom field. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Rule versions review and comparison. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Comparing rules by system. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Bookmarking a rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Searching for a rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Reporting on rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Viewing rule history. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

©2023 Pegasystems Inc

 Pega Platform 8.8 5

Viewing rule versions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

Viewing the generated Java of a rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Viewing the XML of a rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Replacing a string in rulesets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Finding deprecated rules in sections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

©2023 Pegasystems Inc

 Pega Platform 8.8 6

Rules management
A rule is a basic building block of an application that defines its behavior. Pega Platform
applications contain many types of rules that specify different types of behavior.
Because rules are reusable, by implementing them, you can save time and resources
when you build your application.

Rules define the display of forms, the UI fields, the flows for work processes, and
multiple other software elements. The system can reuse rules throughout your
application. For example, in an application for ordering replacements parts, you can
define a UI element to capture an address, and then reuse the rule to capture the
mailing address and billing address for the order.

You configure rules to create a business solution for your organization and customers.
Rules provide flexibility during the development process and help you design
applications more efficiently so that you can implement the rules again in future
projects.

For learning materials about rules, see Creating a rule module on Pega Academy.

• Creating rules

• Organizing rules into rulesets

• Organizing rules into classes

• Rule resolution

• Defining and changing the scope of rules

• Preparing for modifying rules

• Exploring rules in your application

©2023 Pegasystems Inc

 Pega Platform 8.8 7

Related concepts

• Views for cases

• Traditional UI architecture

Related tasks

• Automating work by creating case types

Creating rules
To save time and ensure that your projects meet the needs of your clients, create rules
and data instances using reusable elements of your application. By combining a rule
type, name, class, and ruleset, you provide a unique identity for each rule that you
create.

1. In the header of Dev Studio, click Create, and then select the record category and
type that you want to create.

For example:

To create a data transform, click Create > Data Model > Data Transform.

2. In the record configuration area of the Create form, enter a name for your record
and define its key parts:
a. In the Label field, enter a short description in the form of a sentence that
describes the purpose of the record.
As a best practice, use up to 30 characters. Pega Platform™ appends rule
information to the rule name that you enter to create the fully-qualified
name.
b. Optional: To manually set the name key part of your record to a value that
differs from the default, in the Identifier field, click Edit, and then update the
name.

©2023 Pegasystems Inc

 Pega Platform 8.8 8

The default for this field is To be determined. The system populates this field
with a read-only value based on the sentence that you enter in the Label
field. The system ignores spaces and special characters.
If you manually change the Identifier value, the system no longer populates
this field after you enter a new value in the Label field.
c. In the remaining fields, enter additional key parts for your record.
The number of key parts, types, and restrictions varies by record type. As a
best practice, start each key part with a letter and use only letters, numbers,
and hyphens.
d. Optional: To include other configuration options that this record type
supports, click View additional configuration options.
These options vary by record type and appear only for records that support
Quick Create options. By using the Quick Create option for certain rule types,
you can create rules in the Create dialog box without having to open the
rule form. Rule types with this option include properties, field values, when
conditions, flows, and activities.
3. In the Context section, if the Development branch list appears, select a branch in
which to store your record:
• To create the record in a branched version of the ruleset, select a branch
name.

If the branched ruleset that you provide does not yet exist, the system
automatically creates the ruleset when you create the rule.

• To create the record in an unlocked ruleset version, select [No branch].

The form displays the Development branch list when you define branches in the
current application, or in one of the built-on application layers.
4. Select an application layer in which you want to store the record.
You can store records only in application layers that have access to the selected
development branch.

©2023 Pegasystems Inc

 Pega Platform 8.8 9

Note: The Production Rulesets option appears as the first option in the
stack if your current access group has production rulesets. Choosing this
option restricts only the Add to ruleset field.

5. In the Apply to field, select the class to which this record applies.

By default, the system populates this list with the cases and data types that your
chosen application layer can access. Choose the lowest class in the class hierarchy
that serves the needs of your application.

For example:

Choose MyCo-LoanDiv-MortgageApplication rather than MyCo-LoanDiv- as the

Apply to class for a new flow or property, unless you are certain that the
record can apply to all objects in every class derived from MyCo-LoanDiv-.

Tip: To select a class name that is not a case or a data type, click the View
all link.

6. In the Add to ruleset field, select the name of a ruleset that you want to contain
the record.
If the development branch is [No Branch] or you have no available branches to
choose from, specify a version for the specified ruleset name.
7. Optional: To override the default work item that your application associates with
this development change, press the Down arrow key in the Work item to associate
field, and then select a work item.
For more information about your default work item, see Setting your current work
item.
8. Click Create and open.

©2023 Pegasystems Inc

 Pega Platform 8.8 10

What to do next:

Complete and save the record form on the next screen that opens after you click
Create and open.

• Copying a rule or data instance

• Naming conventions for records

• Rule creation
• Setting rule status and availability
• Searching for a rule
• Configuring system settings

Copying a rule or data instance

Save time and speed up the development process of your application by promoting
reuse of resources. Instead of creating a new record that might be similar to a rule that
already exists, copy an existing rule and then make the necessary changes.Consider a
scenario in which you copy a service-level agreement rule that defines goals and
deadlines for customer service representatives (CSRs) to follow when CSRs review loan
requests, and then change some elements of the rule to adjust it to reviewing mortgage
requests. For example, you can make the goal longer.

Before you begin:

You must have the @baseclass.ToolbarFull or @baseclass.ToolbarSaveAs privilege to

copy rules.

The result of copying an existing rule is a new record with key parts that the system
prepopulates with the values of the original rule. To save the new record, you need to
change at least one key part. The key parts are an identifier, a branch that stores the
record, a class that applies to the record, a ruleset, and a ruleset version.

©2023 Pegasystems Inc

 Pega Platform 8.8 11

Note: Because the Save As form displays a subset of the fields and
functionality that are specific to each data instance, some fields might vary
between different rule types.

1. In the navigation pane of Dev Studio, navigate to the record that you want to copy.

For example:

To copy a service-level agreement rule, click Records > Process > Service
Level Agreement, as in the following example:

Navigating to a record

©2023 Pegasystems Inc

 Pega Platform 8.8 12

2. In the list of instances, open the instance that you want to copy.
3. In the rule form header, select an action to copy the rule:
• If the record is in a locked ruleset, click Save as, as in the following example:

Copying a rule in a locked ruleset

• If the record is in an unlocked ruleset, click Save > Save as, as in the following
example:

Copying a rule in an unlocked ruleset

4. Review the record label and identifier to determine which key parts you can
change.
Consider the following factors:
• If you plan to leave the context for this record unchanged, change the
identifier.
• If the record type that you want to copy has name restrictions, the Identifier
field appears as not editable.
5. In the Context section, review the record context to determine what information
about the storage of the record in your application you can change.
Consider the following factors:
• If you plan to leave the label and identifier unchanged, change at least one
element of the context of the record. You can change a branch that stores
the record, a class that applies to the record, a ruleset, and a ruleset version.

©2023 Pegasystems Inc

 Pega Platform 8.8 13

• If you copy a rule with Final availability and leave the key parts unchanged,
select the same ruleset name and a higher version number. By default, you
cannot override a Final rule with another rule in a different ruleset.
• When you copy a rule, you cannot define the rule availability. The system
clears the rule availability when the record identifier is unchanged, and the
rule meets any of following conditions:
◦ the ruleset is unchanged
◦ the class that applies to the record is unchanged
◦ the original record is specialized by circumstance
For more information about rule availability, see Setting rule status and
availability.
6. Optional: To override the default work item that your application associates with
this development change, press the Down arrow key in the Work item to associate
field, and then select a work item.
For more information about your default work item, see Setting your current work
item.
7. Click Create and open.

Result:

The rule form opens.

What to do next:

Make the necessary changes and then save the rule form.

• Organizing rules into rulesets

• Organizing rules into classes
• Rule resolution
• Defining and changing the scope of rules
• Creating a rule specialized by circumstance
• Troubleshooting newly created rules
• Creating rules

©2023 Pegasystems Inc

 Pega Platform 8.8 14

Naming conventions for records

Give informative and descriptive names to the records that you create in Pega Platform,
such as rules and data instances, to help you manage your resources and provide quick
context for other developers. As a result, you speed up application development and
promote reuse across your application.For example, when you create a ruleset to store
service-level agreement rules for an HR department in your organization, name the
ruleset SLAforHR so that other developers can understand the purpose of the ruleset
and avoid duplicating the record.
As you create new items in your application, it is important to implement consistent
and logical labeling. This approach makes it easier for members of an organization or a
development team to perform the following tasks:

• Find and identify records as you build out applications and configure changes and
enhancements.
• Convey the meaning of the development process and understand the structure of
the application.
• Avoid record duplication and enhance processing efficiency and developer
productivity.

Before creating a record, consider the following actions:

• Look for an existing record, standard or custom, in your application that delivers
the required capability or that you can copy and modify to reduce development
time.
• Assess the likelihood of reuse of the record, as this assessment helps you
determine where to place the record in the class and ruleset hierarchies.

General guidelines for record naming conventions

When you create new records, consider the following naming conventions:

• Choose names that reflect the purpose of the record.

• Keep names short but long enough to make the purpose of the record evident.

©2023 Pegasystems Inc

 Pega Platform 8.8 15

• For readability, start all names with a capital letter. Start additional words within
names with capital letters. Capitalize any acronyms in names.
• Do not include underscores or other special characters, except as noted in
particular scenarios.
• When you create records, the system automatically generates the record identifier
by using text that you enter in the Label field. The system removes spaces and
special characters that you include in the label and capitalizes the first letter of
each word in the identifier.
• Names of records that are part of specific functional groups can start with the
function name, or an abbreviation of the name, followed by an underscore, and
then a record name. Do not use this naming convention for rules from which
other rules inherit. For example, names of data pages start with D_ characters.
• Start the names of active rules, such as activities and flows, with a verb indicating
the main action of the rule. Include a noun or noun phrase that indicates the
element on which the rule operates.
• For passive or object records, such as parameters, properties, work parties,
libraries, and roles, choose nouns or noun phrases that describe the main
purpose of the rule. For example, ProjectGoalDate, ClaimID, or
DefenseAttorney.
• Use hyphens in class names to control pattern inheritance. For example, when
you name a class SLAforHA-ReviewClaims, you indicate that the parent of this
class is the SLAforHA class.

Limitations on name lengths for rule types and objects

When you create objects and rules of different types, consider the following limitations:

• A ruleset name that uses pyRuleSet property can have the maximum length of 128
characters.
• An operator ID value that uses the pyUserName property can have the maximum
length of 128 characters.

©2023 Pegasystems Inc

 Pega Platform 8.8 16

• The internal key of an object that uses the pzInskey property, can have the
maximum length of 255 characters for most tables. Longer file names cause
compilation issues in Windows environments.
• A class name that uses the pxObjClass property, for a class you create can have the
maximum length of 56 characters. The system generates parallel History-
classes for most classes that you create, and consequently reaches the 64
character limit for class names.
• The visible key that uses the pxInsName property can have the maximum length of
128 characters.
• The short description for a record that uses the pyLabel property can have the
maximum length of 64 characters. As a best practice, enter a maximum of 30
characters.
• A property name can have the maximum length of 64 characters.
• The system name, that is a key of the Data-Admin-System data instance, can have
the maximum length of 32 characters.
• A node name can have the maximum length of 32 characters.
• An assignment name can have the maximum length of 32 characters.

Note: When you save your changes, the system does not always enforce size
limits. Names that exceed the defined system limits might cause unusual or
unexpected behavior.

Naming conventions for flow actions and assignments

Use noun and verb combinations for flow actions and assignments, for example
SubmitPurchaseOrder and ReviewJobApplication. Ensure that names are
meaningful to users as the text appears in numerous locations in the end user
interface, for example worklists and menus in user portals.

Additionally, flow actions can reference other records. When you associate a flow action
with an activity or validation record, prefix the flow action name with one of the
following prefixes:

©2023 Pegasystems Inc

 Pega Platform 8.8 17

• For pre-activities, use Pre, for example, PreAcceptCorrespondence.

• For post-activities, use Post, for example, PostAcceptCorrespondence.
• For validation records, user Val, for example ValApproveCorrespondence.

When you name sections and privileges that are related to flow actions, apply the same
guidelines as for flow actions.

Naming conventions for access groups

Choose a name that is unique system-wide, both in the current system and in other
Pega Platform systems that may later host your application. Ensure that the access
group name contains one colon character. Use an ApplicationName:RoleName
format, for example, BakingOperations:Customer or
LoanRequests:Administrator. As a result, you ensure that the name is unique
across multiple applications. Begin the name with a letter and use only alphanumeric,
ampersand, dash characters, and a single colon.

For more information about access groups, see Learning about access groups.

Naming conventions for data objects

Data objects are classes that contain the information such as properties and data pages
that are necessary for a case to accomplish actions or achieve business outcome. For
example, in a banking application, a Customer data object might include properties
such as Name, Phone number, and Address, so that you can conveniently identify and
contact customers. Use nouns that clearly communicate what a data object includes
when you name data objects.

For more information, see Creating a data object.

Naming conventions for database objects

Database objects include tables, views, indexes, and so on created in the Pega Platform
database or other databases that a Pega Platform application uses. In general, name
database tables in accordance with the location of the respective work or data class in

©2023 Pegasystems Inc

 Pega Platform 8.8 18

the Customer Enterprise Class Structure (ECS). Names of standard Pega Platform
database tables begin with pr_, pc_, or pi_. Numerous use cases require creating your
own tables to supplement the standard tables. As a best practice, use the application/
ruleset name as a suffix, for example MyApp_, and to try to resemble the existing name.
For example, name the work table MyApp_work.

For database objects, use the same name as the class or class group and use one of the
following ending suffixes:

• TB for a table
• IN for an index
• SY for synonyms
• SQ for a sequence

Work tables

Map work tables on the implementation layer so that multiple lines of business (LOB)
can use the same framework application to map to different database tables. Name
work tables by using the following format: LOB name_work_workpool name. Ensure that
abbreviations of line of business name and workpool name match the abbreviations in
the Customer ECS, except for DB2 table names.

The following example include sample work tables names:

• For ABCD line of business and Order Intake workpool, name the table
abcd_work_orderintake.
• For Claims line of business and Contracts workpool, name the table
claims_work_contracts.

Work history tables

Name work history tables by using the following format: LOB

name_work_history_workpool name. Ensure that abbreviations of line of business
name and work pool name match the abbreviations in the Customer ECS. For example,

©2023 Pegasystems Inc

 Pega Platform 8.8 19

for ABCD line of business and Order Intake workpool, name the table
abcd_work_history_orderintake.

Data tables

Name division-wide data tables by using the following format: LOB name_data_domain
name. For example, for a Claims line of business and Provider domain, name the data
table claims_data_provider.

Name enterprise-wide data tables in the following format: ent_data_domain name.

For example, for a Networks domain, name the data table ent_data_networks.

Ensure that abbreviations of line of business name and domain name match the
abbreviations in the Customer ECS.

Constraints

Name constraints on a database tables that contain work or data by using the table
name and suffix _PK, which stands for primary key. For example, for a
claims_work_contracts database table, name the constraint
claims_work_contracts_pk.

Naming conventions for files

For records that derive from Rule-File- class, select a name that uses only lowercase
characters to avoid confusion between systems which have case-sensitive file names
systems which do not have case-sensitive file names. Begin the names of files for
related functions with a common prefix character so they appear grouped together in
listings.

Naming conventions for flows

Name flows by using a combination of a verb and a noun that clearly describes a
purpose of the flow, for example Submit an order.

©2023 Pegasystems Inc

 Pega Platform 8.8 20

For more information, see Case life cycle elements.

Naming conventions for functions

Follow Java naming standards, which include initial lower case, then camel case, for the
Function Name key part of a function record, because functions define Java functions.

Naming conventions for HTML streams

For an HTML stream, choose a noun or a noun phrase that indicates the main data that
the stream displays. If possible, relate the name to the name of the activity or action
that displays the stream. For example, WorkSummary. Use camel case in HTML stream
names.

Naming conventions for router activities

Start the name of a router activity with To and end in a noun phrase that indicates the
route destination, such as ToWorkbasket. The following table contains sample router
activities:

Routing activity Purpose

ToAgent Assign to agent entered in parameter.

ToCorrPartyRole Assign to correspondence party role.

ToCostCenterManager Assign to operator designated as the

manager of the cost center.

ToDefaultWorkbasket Assign to the current operator's default work

queue.

ToOrgUnitManager Assign to manager of the current operator's

organization unit.

ToOverallSLA Assign to a list for someone to monitor the

service level. This is a placeholder activity for
copying to your ruleset and modifying to
reference your own service level work queue.

©2023 Pegasystems Inc

 Pega Platform 8.8 21

Routing activity Purpose

Invoke the standard Work-.OverallSLA routing

when the work object is created.

ToProblemFlowOperator Assign to designated operator responsible

for investigating flow issues.

ToWorkbasket Assign to the work queue specified as the

parameter.

ToWorklist Assign to the operator specified as the

parameter.

ToWorkParty Assign to the appropriate work party.

For more information, see Assigning tasks to users.

Naming conventions for service packages

A service package supports the development of services that your application offers. A
service package name becomes the first key part of a set of service records that are
packaged and deployed together. Create a service package data instance for each
service. As a naming convention, use the following format:

<application name><service type><optional deployment type><optional unique part

>

The following list includes sample service package names:

• LOANSSOAP
• LOANSEJBV2
• LOANSEMAIL
• LOANHTTPA, LOANHTTPB, LOANHTTPC

For more information, see Service Packages.

©2023 Pegasystems Inc

 Pega Platform 8.8 22

Naming conventions for work queues and work groups

Use the name that clearly identifies the purpose of the work queue followed by the
suffix WQ, for example, AnalystsWQ or UnderwritingWB.

Work groups usually identify a group of workers that have similar process
responsibilities. Use a name that clearly identifies the purpose of the group followed by
the suffix Group, for example, HelpDeskGroup or BenefitsGroup.

For more information, see Creating a work queue and Creating work groups.

Naming conventions for specific records

For more information about naming conventions for records, refer to the specific
documentation for each record:

• Creating constraints rules

• Creating Declare Expression rules
• Creating a privilege
• Creating a ticket
• Creating a When rule
• Creating rulesets
• Naming conventions for classes
• Naming conventions for properties
• Creating an activity
• Case status values
• Configuring a data transform
• Updating the organizational structure by using the organizational chart
• Creating an operator ID
• Case types
• Stages in a case life cycle
• Processes in a case life cycle
• Steps in a case life cycle

©2023 Pegasystems Inc

 Pega Platform 8.8 23

Naming conventions for other objects

For indexes, views, triggers, and stored procedures, use the same naming criteria as for
activities. Start with a verb that indicates what the database object does, followed by a
noun or a noun phrase that indicates what the view does. End the name with the
appropriate suffix. Maximum length for such names is 15 characters. The following list
includes the suffixes that you can use when you name the objects:

• vw for views
• tr for triggers
• in for indexes
• rp for reports
• sp for stored procedures
• te for trigger events, with further distinctions:
◦ te_ai for After Insert events
◦ te_bi for Before Insert events
◦ te_au for After Update events
◦ te_bu for Before Update events
◦ te_bd for Before Delete events

For example, database view to retrieve employee data records has the name
get_employee_data_vw.

Note: Avoid using the prefixes pwvb_ or pcv_, because the system uses these
prefixes in standard tables.

Related concepts

• Rules management
• Organizing rules into rulesets

©2023 Pegasystems Inc

 Pega Platform 8.8 24

Related tasks

• Organizing rules into classes

Organizing rules into rulesets

To identify, store, and manage the set of rules that define the reusable elements of an
application, organize rules into rulesets. When you group rules into a ruleset, you save
time, because you can reuse an entire ruleset within different applications in your
system instead of reusing or creating individual rules.For example, if you create a
ruleset to store service-level agreement (SLA) rules, you can reuse the ruleset in many
applications that process cases requiring the same SLAs.
You identify each ruleset by name and version number. Each version number consists
of the following parts:

• Two first digits that correspond with a major version, or a release of an

application. A release change represents extensive changes to application
functionality. For example, if an accounting department uses an application to
process expense reports, and the department wants to extend the functionality to
track employee time off for payroll purposes, you create a new release of the
application.
• Two middle digits that correspond with a minor version or an enhancement. For
example, if you want to include an automatic audit in an application that
processes expense report, you create a minor version of the application.
• Two last digits that correspond with a patch version. For example, if you notice
that one field in your application has the wrong label, you create a patch version
to correct the label.

The default version when you create a ruleset is 01-01-01.

When you create a ruleset, you define whether the ruleset is locked or unlocked. By
creating a locked ruleset, you protect the ruleset from accidental changes because
developers must enter a password before editing the ruleset. You can also define

©2023 Pegasystems Inc

 Pega Platform 8.8 25

passwords for other actions, such as adding a new ruleset version, or updating the
ruleset.

To allow members of your development team to work simultaneously on different

features, create branch rulesets that developers use as isolated sandboxes. As a result,
you reduce the risk of overwriting work, and improve the quality of your application.

For learning materials about rulesets, see a Rulesets topic on Pega Academy.

• Creating rulesets

• Defining the security of a ruleset

• Categorizing a ruleset

• Deleting a ruleset

• About the Ruleset Maintenance wizard

• Production rulesets

• Creating applications
• Application Structure landing page

Creating rulesets
Reduce development time and costs by creating rulesets. After you create a ruleset, you
can group rules, which are reusable elements of your application, together in a logical
way in the ruleset. As a result, you conveniently manage, maintain, and reuse your
rules.For example, you can create a ruleset that stores service-level agreements (SLAs),
and a separate ruleset for case notifications. If you want to make any changes to the
SLA ruleset, your modifications are granular and you avoid the risk of unintended
changes occurring in the case notifications ruleset. You can also provide a way for
members of your development team to work in isolated sandboxes by creating branch
rulesets.

When you create new rulesets, consider the following guidelines:

©2023 Pegasystems Inc

 Pega Platform 8.8 26

• Create a new ruleset with a top-level class that inherits directly from @baseclass.
• Use names that are easy to remember and unique for each ruleset.
• Use names that clearly convey the purpose of the ruleset; avoid using acronyms
that might be difficult to decode. For example, name your ruleset
UPlusTelcoContracts instead of UPTC.
• Always begin your ruleset name with a phrase that clearly identifies your company
and the business purpose. This convention also prevents potential ruleset
conflicts.
• Do not use Pega or Pega- as a prefix for your ruleset names. These prefixes are
restricted to Pega Platform internal use and can cause unexpected behavior.
• The maximum length of a ruleset name is 32 characters. Avoid using spaces in
ruleset names.
• Avoid the use of special characters such as dashes (-), underscores (_), plus signs
(+), or quotes (“ ”). The system does not permit the saving of rules with these
attributes.
• For more information about using patterns for the ruleset version number, see
Organizing rules into rulesets.

• Creating a ruleset and a ruleset version

• Configuring ruleset version settings

• Copying rulesets

• Organization data instances

• Organization Unit data instances
• Divisions
• Operators

Creating a ruleset and a ruleset version

For easier maintenance and development of your application, create rulesets so that
you can categorize the rules that your application uses based on usage, purpose, and
dependencies. You can also create newer versions of existing rulesets to keep track of

©2023 Pegasystems Inc

 Pega Platform 8.8 27

version control. As a result, you can quickly locate and analyze the elements that you
change in your application. For example, you can create a ruleset that stores APIs that
your organization provides. When you want to enhance the APIs, create a new ruleset
version, so that you can track and manage the changes over time.

1. In the header of Dev Studio, click Create > SysAdmin > RuleSet.
2. Create a new ruleset or ruleset version:
• To create a new ruleset, in the RuleSet Name field, enter a unique name for
your ruleset.

The maximum length of a ruleset name is 32 characters. Avoid using spaces

in your ruleset names.

• To create a new ruleset version, in the RuleSet Name field, press the Down
arrow key, and then select the ruleset for which you want to create a new
version.

Result:

The system populates the version and description of your ruleset.

3. Optional: To change the version number of your ruleset, in the Version field,
enter a new value.

For example:

Enter 01-01-03.

By default, for a new ruleset version, the system enters 01-01-01 as the version
number. For existing rulesets, the system increments the highest version by one
patch number. In a version number, the two first digits correspond with the
release, the middle digits correspond with the minor version or enhancement,
and the final digits correspond with the patch version.
4. Optional: To change the description of your ruleset, in the Description field, enter
a new value.

©2023 Pegasystems Inc

 Pega Platform 8.8 28

For example:

Enter SampleRuleset:01-01-03

By default, the system forms the description by combining the ruleset name and
version number.
5. Click Create and open.

What to do next:

Configure version settings for your ruleset. For more information, see
Configuring ruleset version settings.

Related tasks

• Creating branch rulesets

Related information

• Rule check-in process

Configuring ruleset version settings

For improved management of your application, define the behavior of your ruleset and
how it interacts with other elements of your application by configuring ruleset version
settings. For example, you can lock a ruleset to keep it in its original state, or require
development approval for checking in rules into the ruleset, in order to track and
manage changes.

Before you begin:

Create a ruleset or a ruleset version. For more information, see Creating a

ruleset and a ruleset version.

©2023 Pegasystems Inc

 Pega Platform 8.8 29

1. Expand the SysAdmin category, and then click RuleSet.

2. In the Instances of Ruleset section, select the ruleset that you want to edit.
3. On the Edit Ruleset form, in the Validation mode section, define the ruleset
validation settings:
• To validate the ruleset within the application context only, select Application
Validation.
• To validate the ruleset based on the prerequisites defined in another ruleset,
select Ruleset Validation, and then in the Required rulesets and versions
field, enter the rulesets that you want to use as the validation prerequisites.
4. Optional: To require development approval for checking in rules for this ruleset
version, select the Approval required check box.
When you require an approval to check in rules, you minimize the risk of
unwanted or accidental changes to the ruleset.
5. Optional: To reserve the rule for future use, in the Effective Start Date field, select
a new date.
By default, the system enters the day of the ruleset creation.
6. Optional: To protect the ruleset from accidental changes, lock the ruleset:
a. Click Lock and save.
b. In the Lock RuleSet Version dialog box, enter and then confirm a password.
c. Click Submit.
7. Save your changes to this ruleset version by clicking Save in the ruleset version
area.
8. Optional: To define more ruleset versions, click Add a row, and then repeat steps
3 through 7.
9. Click Save.

• Ruleset validation modes

Related tasks

• Categorizing a ruleset
• Deleting a ruleset

©2023 Pegasystems Inc

 Pega Platform 8.8 30

• Organizing rules into classes

• Moving rules
• Defining the security of a ruleset

Ruleset validation modes

Ruleset validation is a Pega Platform™ mechanism for ensuring that rules that an
application references are available on the target system and accessible by the
application. Ruleset validation does not affect rule resolution at run time but Pega
Platform applies it only at design time.

For relevant training materials, see Ruleset validation.

Pega Platform provides two types of ruleset validation:

Application validation (AV) mode

Validates a ruleset only within the application context. When you configure a
ruleset to use AV, Pega Platform determines which rules are valid to reference at
design time without using ruleset prerequisites.
Ruleset validation (RV) mode
Validates a ruleset based on the prerequisites that you define in another ruleset.

Note: Using AV mode offers performance advantages over the alternative RV

mode.

Related tasks

• Configuring ruleset version settings

Related information

• Validation tool

©2023 Pegasystems Inc

 Pega Platform 8.8 31

Copying rulesets
To speed up application development, reuse resources by copying rulesets. For
example, you can copy a ruleset if you want to modify only some of the rules that the
ruleset includes, to increase flexibility of your application. For instance, if you create an
application that processes loan requests and mortgage requests, you can copy a ruleset
that includes system-level agreement rules, and then modify specific rules to meet your
unique business needs.

When you copy a ruleset, the system copies the ruleset versions, security, category, and
history settings.

1. In the header of Dev Studio, click Configure > Application > Structure > RuleSet
Stack.
2. On the RuleSet Stack tab, in the Current Application section, click the ruleset
that you want to copy.
3. In the header of the Edit Ruleset form, click the Down arrow next on the Save
button, and then click Save as.
4. Optional: To provide additional information about the ruleset, in the Short
description field, modify the default description.
5. In the RuleSet Name field, enter a new, unique ruleset name.
6. Optional: To change the version number of your ruleset, in the Version field,
enter a new value.

For example:

Enter 01-01-03.

By default, for a new ruleset version, the system enters 01-01-01 as the version
number. For existing rulesets, the system increments the highest version by one
patch number. In a version number, the two first digits correspond with the
release, the middle digits correspond with the minor version or enhancement,
and the final digits correspond with the patch version.

©2023 Pegasystems Inc

 Pega Platform 8.8 32

7. Optional: To change the description of your ruleset, in the Description field, enter
a new value.

For example:

Enter SampleRuleset:01-01-03

By default, the system forms the description by combining the ruleset name and
version number.
8. Click Create and open.

What to do next:

Modify the copied ruleset:

• Provide new ruleset version, validation, and locking settings. For more
information, see Configuring ruleset version settings.
• Configure further ruleset security options. For more information, see
Defining the security of a ruleset.

Related tasks

• Defining and changing the scope of rules

• Deleting a ruleset

Defining the security of a ruleset

Complete the Security tab on the Ruleset form to update security information for a
ruleset. For example, you can control who can change rules in a ruleset, and prevent
potential conflicts when two or more users attempt to change one rule at the same
time.

You can also lock the ruleset or its versions by requiring developers to enter a password
when they do the following:

©2023 Pegasystems Inc

 Pega Platform 8.8 33

• Update a ruleset or update class rules in a ruleset.

• Add, copy, or update versions on the Versions tab of a ruleset.

1. In the Records explorer of Dev Studio, click SysAdmin > RuleSet, and click a rule to
open it.
2. Click the Security tab.
3. If you defined a password that a user must match to update the ruleset, in the
Enter password values section, in the To update this RuleSet field, enter the
password to unlock the ruleset.
4. To indicate that this ruleset contains rules that tailor, override, and extend an
application, rather than define an application, in the Rule management section,
complete the following fields:
a. To specify that a ruleset is not intended to be moved to other Pega Platform
systems, select Local customization?.
This setting is advisory only and does not affect the ruleset functionality.

Note: If you select this option, do not select Use check-out?.

b. To enable developers to check out this ruleset when updating it, select Use
check-out?.
As a best practice, select this option to avoid the risk of multiple developers
updating a ruleset and overwriting each other's changes.
c. Optional: To use a flow rule to manage development and check-in on this
ruleset, in the Work class used for approval process field, enter the work
type to which the flow rule that controls check-ins applies.

Note: Leave this field blank if you did not select Use check-out? in
step 4.b. The Work class used for approval process field supports
advanced rule management features, which are useful when a large
development team is involved or when a development leader wants

©2023 Pegasystems Inc

 Pega Platform 8.8 34

to review each change made by others on the development team

before the rule is checked in.

For more information about checking in rulesets, see Configuring the rule
check-in approval process.
d. Optional: In the Work flow to use for approvals field, enter the name of the
flow rule that controls rule check-in for this ruleset.

Note: Leave this field blank if you did not select Use check-out? in
step 4.b. The Work flow to use for approvals field supports
advanced rule management features, which are useful when a large
development team is involved or when a development leader wants
to review each change made by others on the development team
before the rule is checked in.

5. Optional: Use the Define passwords section to prohibit users from adding or
updating versions of this ruleset, or updating this ruleset.
Lock the setting by entering passwords in the following fields. When you save the
rule, the field is replaced by a check box. If you leave a field blank, no password is
required.
a. In the To Add a Ruleset Version field, enter a password that the user must
match before creating (beneath the version array) or copying a version for
this ruleset on the Versions tab.
b. In the To Update a Ruleset Version field, enter a password that the user
must match before updating a version on the Versions tab.
c. In the To Update this Ruleset field, enter a password that a user must match
when updating this ruleset. This restriction includes updates to the versions
on the Versions tab.

©2023 Pegasystems Inc

 Pega Platform 8.8 35

Note: To unlock the To Add a Ruleset Version and To Update a

Ruleset Version settings, clear the check box and save the rule.

To unlock the To Update this Ruleset setting, clear the check box,
enter the password in the To Update this Ruleset Name field, and
save the rule. Lock this setting to prevent changes to the To Add a
Ruleset Version or To Update a Ruleset Version settings.

6. Click Save.

• Deleting a ruleset
• Organizing rules into rulesets

Categorizing a ruleset
Complete this tab to control the category of this ruleset and to provide additional
information for Component rulesets.

In most cases, accept the default Standard ruleset type.

Note: The Standard ruleset type is different from the Pega-zzzz standard
ruleset that defines Pega Platform.

1. In the Records explorer of Dev Studio, click SysAdmin > RuleSet, and click a rule to
open it.
2. Click the Category tab.
3. In the RuleSet Type field, select the category to which this ruleset belongs.
Your selection affects where this ruleset appears in a requestor's ruleset list, and
how rule resolution finds the rules in the ruleset.
• Standard – A "normal" ruleset that can contain all types of rules.

©2023 Pegasystems Inc

 Pega Platform 8.8 36

Note: All rulesets created in Pega Platform 5.3 and earlier belong to
this category.

• Component – A restricted ruleset designed to encapsulate functional or

capabilities that operate only on embedded pages. Rules in a component
ruleset are designed and intended for reuse in multiple systems and
applications.
• Shared – A restricted ruleset designed for reuse that operates on top-level
pages only. See shared ruleset for the restrictions.

CAUTION: Choose this value carefully. Although you can change ruleset
types other than Override later, Pega Platform does not then check
whether existing rules in the ruleset meet the restrictions of the Shared or
Component categories.

4. If you chose the Component rule type in step 3, the Property to embed in
application section displays. To establish communication between Pega Platform
and a component application, complete the following fields:
a. In the Recommended Name field, enter a Page -mode property that is
made available to both the primary (calling) application and the component
ruleset.
This provides communication between the primary application and the
component application.
b. In the Page Name field, enter a clipboard page name that the component
can access to pass values to and from the calling application.
c. In the Page Description field, enter a description for the clipboard page.
d. Click Add a row to add additional properties.
5. Optional: To add test case rules to the ruleset, in the Test automation settings
section, select Use this ruleset to store test cases.
For more information, see Creating unit test cases for rules.

©2023 Pegasystems Inc

 Pega Platform 8.8 37

6. Click Save.

• Deleting a ruleset
• Organizing rules into rulesets

Deleting a ruleset
Use the RuleSet Delete tool to delete an entire ruleset or a specific version of a ruleset,
or to restore a ruleset previously deleted with this tool.

Before you begin:

• Don't delete a ruleset version that contains rules that are in use at the time.

• Review access groups to confirm that they do not reference application

rules to be deleted or the ruleset version to be deleted.

• Review operator IDs that might reference skill rules (Rule-Admin-Skill) that
will be deleted.

• Review listener data instances (such as Data-Admin-Connect-EmailListener) to

confirm that they do not reference service rules that will be deleted.

• Check for other rules or data instances that may reference the RuleSet or
version deleted, including:
◦ Application rules ( Rule-Application rule type)
◦ Other ruleset versions (as prerequisites)
• If any checked-out rules are from the deleted ruleset version, open each
checked out rule and delete it with the Delete Checkout toolbar icon.

Note:

©2023 Pegasystems Inc

 Pega Platform 8.8 38

If the ruleset includes one or more concrete classes derived from the Work-
base class, and there are instances (work items) in the classes, they are deleted
too.

This tool does not delete instances of the History-Rule class or Index- classes
that may reference the ruleset or version. Such orphaned records do not
require much space and are harmless.

1. In the header of Dev Studio, click Configure > System >Refactor > RuleSets >
Delete a RuleSet to start the tool.
2. Select the ruleset to be deleted in the Original RuleSet field.
3. Optional: Select a ruleset version to be deleted in the RuleSet Version field.
4. Click the Delete button to begin processing. This may take several minutes.

Result:

The system creates a backup of the ruleset in PRPC's explicit temporary

directory. A status area shows progress and the results of the operation.

5. If errors occur, click the Total Number of Errors link in the lower right corner of the
display form to see any error messages. This list can't easily be accessed after you
close the form; print the list so you can research and address the errors.
6. Click Close.

Result:

The system saves the deleted ruleset in a file called

"RuleSetName_RuleSetVersion_DELETE.zip" in PRPC's temporary directory.

©2023 Pegasystems Inc

 Pega Platform 8.8 39

What to do next:

If you deleted the ruleset by accident, enter the ruleset and version into the
Delete a RuleSet form, and then click Restore.

• About the Ruleset Maintenance wizard

• Organizing rules into rulesets

About the Ruleset Maintenance wizard

The Ruleset Maintenance wizard helps you copy rulesets and ruleset versions into new
versions, merge several ruleset versions into one version, move rules out of one ruleset
into another, or change a ruleset version's number.

• Use the Move operation to rename a ruleset: the process moves the rules from
the existing ruleset into the new ruleset you specify, and then deletes the source
ruleset.
• For Copy operations, the target rules, if they exist, must be unlocked and checked
in before the operation can be completed.
• For Move operations, the source and target rules, if they exist, must be unlocked
and checked in before the operation can be completed.
• For Change a Version operations, the source rules should be checked in.

Operations of this wizard depend on the Pega-RuleRefactoring agents. If you use this
wizard, confirm that the Pega-RuleRefactoring agents are enabled on at least one node
of your system.

Moving a ruleset

To move a ruleset, select an existing ruleset and specify a target name and, optionally, a
version. The wizard processes the source rules in each ruleset version in the ruleset
and any non-versioned rules associated with the ruleset. The RuleSet and RuleSet
Version fields of each rule are updated to the values specified as the target. The result

©2023 Pegasystems Inc

 Pega Platform 8.8 40

is that the rule appears to have been deleted from its source ruleset and copied into
the target ruleset. The value of the rule's pzInsKey does not change.

The handling of multiple ruleset versions in the ruleset depends on whether you specify
a target version:

• If you move a ruleset without specifying a target version, the wizard preserves the
structure and contents of the source ruleset's versions under the target ruleset.
• If you move a ruleset and specify a target version, ruleset versions in the source
ruleset are merged by skimming the rules to the specified version under the
target ruleset. That is, the highest-versioned instance of each rule in the source
ruleset versions is moved to the target ruleset and specified ruleset version.

For example, if you move a ruleset containing rules with ruleset versions 01-01-01,
01-01-02 and 01-01-03 into a new target ruleset and specify a version of 01-02-01, the
target ruleset version will contain the highest version of all the source rules contained
in versions 01-01-01, 01-01-02 and 01-01-03 with lower-versioned duplicates dropped.
In this example, if a rule is duplicated in both 01-01-01 and 01-01-02, the rule will be
moved from 01-01-02 to the new ruleset name with ruleset version 01-02-01, and the
duplicate rule in 01-01-01 will be dropped.

When you move a ruleset, the wizard also updates the references to affected ruleset
versions in the following rules or data instances anywhere in the system, so they
reference correctly the versions that exist after the move:

• Rule-Obj-Class • Rule-Application-UseCase
• Rule-Access-Deny-Obj • Rule-Connect-SOAP
• Rule-Access-Role-Name • Rule-Declare-Pages
• Rule-Access-Role-Obj • Rule-RuleSet-Name
• Rule-Application-Requirement • Rule-RuleSet-Version
• Rule-Application

You cannot copy a ruleset.

©2023 Pegasystems Inc

 Pega Platform 8.8 41

Copying or moving a ruleset version

Copying a ruleset version performs the same function as the Save As toolbar action.
The original source ruleset version does not change. Each target rule that is created is
identical to the original source rule with the following exceptions:

1. You must specify a ruleset version for the target rules that is different than that of
the source rules.
2. The wizard creates a new pzInsKey field value for the target rules using the actual
create date/time as one of the values in the construction the new target pzInsKey.
The create date/time value is the only difference between the data that makes up
the source and target pzInsKey values.

As with moving a ruleset, moving a ruleset version changes the source rules. The wizard
updates the RuleSet Version fields of each rule to the values specified as the target. The
result is that the rule appears to have been deleted from its source ruleset version, and
copied into the target ruleset version. In a move, the value of the rule's pzInsKey does
not change.

Merging rulesets and ruleset versions

You can merge multiple source ruleset versions belonging to the same or different
rulesets. For example, you can "skim" the ruleset by collecting only the highest version
of every rule in the ruleset versions into the target, or you can compress the rulesets
down to a lower level (01-01-01) or another designated level. You control the merge by
specifying the target version and the order in which the ruleset versions will be
processed.

When you select the ruleset versions, you establish the order of precedence by the
order in which you list them in the wizard interface. The wizard processes the rules in
the order listed, top-to-bottom, collects the first version of every rule it finds, and drops
other duplicate rules:

©2023 Pegasystems Inc

 Pega Platform 8.8 42

• The wizard first processes rules from the first ruleset version listed, and then
discards duplicate rules in the following versions in the list.
• Then the wizard processes any remaining rules in the second ruleset version in
the list, dropping any that are duplicates of what it has already processes.
• Processing continues in the same way down the list of versions.

Note: Compress rulesets with prerequisites beginning with the ruleset of least
dependency. For example, if ruleset A requires ruleset B as a prerequisite, and
ruleset B requires ruleset C as a prerequisite, then you should compress the
ruleset A first, then B, and finally C. If you compress the rulesets in the order C,
B, and A, you risk losing some rules that you expected to retain.

When you merge rulesets or ruleset versions, you have the option of deleting the
sources once the merge is complete. However, if you merge ruleset versions and opt to
delete the sources, the source versions are deleted, but not their ruleset(s).

When you merge ruleset versions, you have the option of excluding categories of non-
versioned rules. The categories are listd at the bottom of the form. Clear the check box
to exclude a category.

Note: When you select Libraries and Functions from the list of non-versioned
rules, all functions are merged when the ruleset name has changed. When the
ruleset name is the same and only the version has changed, functions are
treated like versioned rules and only patch functions are merged.

For an example of the merge operation, see the article How to merge RuleSets using the
RuleSet Maintenance wizard.

Changing a ruleset version number

You can change the version number for a particular ruleset version, whether or not the
version which you designate as the new number already exists. The target version

©2023 Pegasystems Inc

 Pega Platform 8.8 43

belongs to the same ruleset as the source version. All rules, including non-resolved
rules, from the source ruleset version become part of the target version. All rules retain
their original pzInsKey values, and therefore retain their History.

When the change is complete, the wizard deletes all rules in the source version.

Rule conflicts

For move, copy, and change operations, you can specify how to handle conflicts if the
same rules are found in both the source and the target. You can choose to overwrite
the target rules with the source rules, or to not move or copy the source rules that
conflict, leaving the target rules unchanged. If you choose not to overwrite the rules,
the Summary page of the wizard lists the rules in the source that were skipped because
they were in conflict with the target.

Locked ruleset versions

The wizard does not change rules that belong to locked ruleset versions. If a ruleset
version that will be changed by the wizard operation is locked, you are prompted for
the password to unlock the version before proceeding. To copy a ruleset version the
target rules cannot be locked. The source rules can be locked, since they are not
changed by the copy operation. To move a ruleset or ruleset version, both the source
and target rules must be unlocked.

Checked-out rules

As a best practice, make sure that all rules are checked in before you move or copy a
ruleset or ruleset version. Click Configure > Application > Development > Checked Out
Rules. Complete the parameters and click Run. Review the resulting report to confirm
that no rules from that ruleset version are checked out.

If the wizard encounters rules to be modified that are checked out, it displays a warning
page and provides a report of the checked-out rules. From the report window you can
open the rules and check in the ones for which you have permission, or save a list of
the rules in a spreadsheet.

©2023 Pegasystems Inc

 Pega Platform 8.8 44

You must check in any rules you have checked out or arrange for any rules in the report
that are checked out by other users to be checked in before you can complete the
wizard. If you exit the wizard to arrange for rules to be checked in, you must restart the
wizard from the beginning.

Affected rules and data instances

The wizard automatically adjusts any references to ruleset versions in the following
rules or data instances, system wide, to match the versions that exist after a merge or
move:

• Ruleset versions ( “prerequisite” field)

• Rule-Application (lists on the General tab)
• Organization data instance (listing ruleset versions here is possible, deprecated)
• Access group data instances

Prerequisites and preparation

Before running the RuleSet Maintenance wizard, consider the following guidelines:

• Back up your Pega Platform system before performing operations with this
wizard.
• You can only copy or move rulesets or ruleset versions that are in your ruleset
List.
• Make sure the rules that will be modified by the operation you specify are
unlocked and checked in. As described above, the wizard will warn you if it
encounters locked or checked-out rules during the copy or move, but it is a best
practice to make sure that all the rules you will operate on are unlocked and
checked in before running the wizard.

When you are working with ruleset versions, the Copy missing RuleSet Prerequisites
check box appears at the bottom of the first form of the wizard. Select this check box to
have the wizard copy any prerequisite rulesets that the ruleset version that results from
your process will require.

©2023 Pegasystems Inc

 Pega Platform 8.8 45

Starting the wizard

Select the Dev Studio >System > Refactor >RuleSets menu item, then click Copy/Merge
RuleSet to start the wizard. Then select the operation you wish to execute.

For help in completing the first form, see RuleSet Maintenance wizard.

Recommended next steps

This wizard does not modify references to rulesets that are deleted or modified. Repair
any references to rules that have been moved by the wizard by replacing references to
the source ruleset with the target or another ruleset. In particular,

• If a ruleset to be moved is referenced in an application rule, be sure to update the

references on the application rule form:

- Application RuleSets section on the General tab

- Component and Shared RuleSets section on the General tab

- Production RuleSets section on the General tab

• Update any references to the old ruleset in Access Groups, including the local
customization section on the Settings tab.

Recovering merged rulesets

Note: Before merging the rulesets, the tool creates a backup of each rule
named Bkup_SourceRuleSet.zip and Bkup_TargetRuleSet.zip. If needed, you can
use the Import .zip facilities to recover the original rulesets.

©2023 Pegasystems Inc

 Pega Platform 8.8 46

Logging

Each execution of this wizard creates an instance of the Log-Merge-RuleSet class,

including error messages or other results. The key to this instance is the date and time
the wizard was started.

Class rules do not have a version. Do not delete Class rules (or other rules that have no
version) if any version of the ruleset remains in use.

In some organizations, audit or compliance policies might prohibit deleting old rules,
even if they are not in use.

RuleSet Maintenance wizard step 1

The RuleSet Maintenance wizard helps you copy rulesets and ruleset versions into new
versions, merge several ruleset versions into one version, move rules from one version
into another, and change a version's number.

Preparation and prerequisites

For Copy operations, the target rules, if they exist, must be unlocked and checked in
before the operation can be completed. Source rules should be checked in.

For Move operations the source and target rules, if they exist, must be unlocked and
checked in before the operation can be completed.

For Change a Version operations, the source rules should be checked in.

The wizard uses the full-text search indexes to reduce search time and increase
accuracy. If full-text search for rules not enabled for your system, the process may
operate much more slowly, and may not locate all data instances that may need to be
updated.

When you are working with ruleset versions, the Copy missing RuleSet Prerequisites
check box displays at the bottom of the first form of the wizard. Select this to have the

©2023 Pegasystems Inc

 Pega Platform 8.8 47

wizard copy any prerequisite rulesets that the ruleset version that results from your
process will require.

For a checklist of other prerequisites and preparation steps, see About the RuleSet
Maintenance wizard.

Completing the form

1. Access the ruleset wizard landing page by clicking Configure > System > Refactor
> Rulesets, and click Copy/Merge RuleSet.

2. Select one of the four radio button options: Copy, Move, Merge, or Change a
Version.

Copying creates the target rules and leaves the source rules unchanged. Moving,
merging, and changing create the target rules and delete the source rules.

You can perform all four operations on ruleset versions. You can only move or
merge rulesets.

3. Select the ruleset or ruleset versions to be processed.

Select the ruleset or version from the left-hand list, Available Source RuleSet(s),
and move it to the right-hand list, Order of precedence during Copy/Move/Merge.
You can drag your selection, double-click it, or select it and click the right-facing
arrow icon between the lists to move it.

4. Adjust order of precedence, if needed.

If you are operating on multiple ruleset versions, they will be processed in the
order listed, top-to-bottom. That is, rules are first processed from the first ruleset
version listed and duplicate rules in the following versions in the list are dropped.
Then any remaining rules are processed in the second ruleset version in the list
and dropped from the following versions. Processing then continues in the same
way down the list of versions. To move a version higher or lower in the list, select

©2023 Pegasystems Inc

 Pega Platform 8.8 48

it and then click the up or down arrow. You can also click a selection and drag it to
a higher or lower position in the list.

5. Specify a Target name and, if wanted, a version.

Enter the name of the ruleset or ruleset version that the selected rules are to be
copied, moved, or merged into; or the new version number for the ruleset
version. If you provide a new name, the wizard creates the target ruleset. If the
target exists, source rules that also appear in the target are processed according
to how you set the Overwrite.option (see the next step).

If you move a ruleset and specify a target version, ruleset versions in the source
ruleset are merged by skimming the rules to the specified version under the
Target ruleset. That is, the highest versioned instance of each rule in the source
ruleset versions is moved to the target ruleset and specified ruleset version.

If you move a ruleset without specifying a target version, the source ruleset
versions are preserved under the target ruleset.

If you copy or move a ruleset version, you must provide a target version. If you
copy or move multiple ruleset versions, they will be merged into the target version
following the order in which you have listed them in the Order of precedence...
list.

Note that when you change a ruleset version number, the source and target
ruleset names must be the same.

6. For Copy, Move, and Change, specify the method to resolve rule conflicts.

If you select Yes , source rules that duplicate existing target rules replace the
target rules in the processed ruleset. If you select No , source rules that duplicate
existing target rules are not processed, and the target rules are left unchanged.

7. For Merge, specify whether the source rulesets or ruleset versions are to be
deleted after the merge is complete. Select Yes to delete the sources; No to

©2023 Pegasystems Inc

 Pega Platform 8.8 49

retain them. If you are merging ruleset versions and opt to delete the source
versions, their parent rulesets are not deleted.

8. When you merge ruleset versions, a display at the bottom of the form shows
categories of non-versioned rules, and the number of rules of each type affected
by changes to the ruleset versions you have selected and placed in the second list.
You can exclude any category by clearing the check box to the left of its name.

Note: When you select Libraries and Functions from the list of non-
versioned rules, all functions are merged when the ruleset name has
changed. When the ruleset name is the same and only the version has
changed, functions are treated like versioned rules.

9. Click Next to continue to the next form in the wizard. See RuleSet Maintenance
wizard 2. Click Cancel and then click Done to cancel the wizard.

About the RuleSet Maintenance wizard

RuleSet Maintenance wizard step 2

On this page confirm that the selected operation is as you have specified. Be sure that:

• You have selected Copy, Merge, Move, or Change as intended.

• You have specified the correct target ruleset or ruleset version.
• You have specified the correct source ruleset or ruleset version(s).
• For Copy, Move, or Change, you have selected the response to rule conflicts
between the source and target as intended: overwrite or not.
• For Merge, you have specified whether to delete the source rulesets or ruleset
versions when the merge is completed.
• For ruleset versions, you have specified whether to copy prerequisites the version
requires.

©2023 Pegasystems Inc

 Pega Platform 8.8 50

The page displays a list of data instances that may be affected by the procedure. Select
all entries that you want to update so that they will continue to work with the target
ruleset or ruleset version.

You have the option of running the wizard as a background process: this can be useful
when moving or merging rulesets containing a large number of rules, as the process
may take several minutes to complete. To select this option, click the Yes radio button
beside the Run as a background process label.

The Pega Platform sends an email notifying you when the process is complete. If no
email server has been set up for the Pega Platform and you select this option, a
message appears stating that an email will be sent once you set up an email server.

You can still run the wizard as a background process, but if outbound email is not set
up, the Pega Platform cannot send you an email when the process completes. The
wizard form provides you with the ID of the process so you can review it at any time,
and displays a message at the end of the process: see RuleSet Maintenance Wizard 3.

Depending on the process you selected in the first screen, the continuation button's
label will read Copy, Rename Version, and so on. If you are satisfied with the settings,
click the button to begin the process and to continue to the next step. See RuleSet
Maintenance wizard 3.

To change any of the settings, Click <<Back to return to the previous step.

Click Cancel and then click Done to cancel the wizard.

About the RuleSet Maintenance wizard

RuleSet Maintenance wizard step 3

If you opted to run the wizard as a background process, a message displays on the
page stating that your request is being processed and that you will receive an email
notification once it has completed.

©2023 Pegasystems Inc

 Pega Platform 8.8 51

Place the provided reference number in the Search facility and click the magnifying
glass. The facility opens the wizard at its current form so you can check its status.

When the process is complete, this form displays a summary of the changes that have
been made, including the number of rules considered and selected. Depending on the
process and the options you selected, up to four links provide access to lists of

• rules processed
• data instances processed
• rules in conflict
• processing errors

If there were no data instances to process, errors, or conflicting rules, the

corresponding links do not appear.

Click any link to display the list. In the report that is displayed, you can click any row to
review that rule in detail. To save a copy of a list in spreadsheet form, click Export Page
to Excel at the top of the list.

After you have closed any reports you have opened, click Done to exit the wizard.

About the RuleSet Maintenance wizard

RuleSet Maintenance — Locked Rules

If the wizard finds rules to be modified in locked rulesets or locked ruleset versions, this
form displays a list of the locked rulesets or ruleset versions with a Password field for
each.

• To continue, provide the password to unlock each ruleset or ruleset version and
click Next. The wizard unlocks the ruleset or ruleset version, operates on the rules
as specified, and then re-sets the lock.
• If you cannot provide the passwords, click Cancel to exit the wizard, arrange to
unlock the rules in Pega Platform, and then rerun the RuleSet Maintenance wizard
from the beginning.

©2023 Pegasystems Inc

 Pega Platform 8.8 52

• Click Back to return to the previous page.

About the RuleSet Maintenance wizard

RuleSet Maintenance — Checked-Out Rules

If the wizard finds that rules to be modified are checked out, this page displays a
warning. Click Display to open a report of the checked-out rules. From the report
window you can open the rules or Click Export to Excel to save a list of the rules in a
spreadsheet.

You cannot proceed while rules to be modified are checked out. Check in any rules you
have checked out and arrange for any rules listed as checked out by others to be
checked in. When all rules are checked in, click Next>> to continue.

If you exit the wizard to arrange for rules to be checked in, you will need to restart the
process from the beginning.

Click <<Back to return to an earlier step, or click Cancel and then click Done to cancel
the process and exit the wizard.

About the RuleSet Maintenance wizard

Production rulesets
To allow users to modify a rule in production, define the rule in a production ruleset.

Note: This article replaces the archival article "KB 25289 - How to configure
production RuleSets and WorkPools."

Production rulesets can be listed for applications and for access groups. If an
application has production rulesets, you list all of them in the application rule. In an
access group, you list the rulesets that are delegated to the access group. Typically, you
grant this permission to managers, not to case workers.

©2023 Pegasystems Inc

 Pega Platform 8.8 53

As a best practice, do not include any Work- classes (classes for work objects) in
production rulesets.

Define the modifiable rule in a regular application ruleset (which is locked), as well as in
a higher-version unlocked production ruleset. The rule in the production ruleset takes
precedence at runtime since it is a higher-ranked ruleset.

The ruleset concept does not apply to data instances.

• Viewing your application ruleset list

• Defining a run-time configuration for an access group
• Delegating a rule or data type

Organizing rules into classes

For more efficient management of your applications, organize rules into classes. A class
describes a collection of rules or other objects, such as properties, activities, and HTML
forms, that are available to other, child classes, or to instances of the class. Pega
Platform organizes classes into a hierarchy, in which the system searches from the
current class upwards when looking for a rule to apply.

Within an application, Pega Platform groups rules into classes according to their
capacity for reuse. Each application consists of the following types of classes:

Work class
The Work class contains the rules that define the processing of cases, such as
processes, data elements, and user interfaces.
Integration class
The Integration class contains the rules that define interactions between the
application and other systems, such as an external database.

Data class
The Data class contains the rules that define the data objects that your application
uses, such as customer information.

©2023 Pegasystems Inc

 Pega Platform 8.8 54

Because you can reuse rules between classes, you save time and reduce your
development costs.

Some classes do not have rule forms. An example is the System-User-Dashboard class. If
you open an instance of such class, you can only view the XML of this class instance.

• Understanding class layers

• Understanding class hierarchy and inheritance

• Understanding external classes

• Creating classes

• General tab on the Class form

• Locking tab on the Class form

• Advanced tab on the Class form

• External Mapping tab on the Class form

• Finding the class of a rule

• About the Rename a Class wizard

• About the Delete a Class wizard

• Understanding class hierarchy and inheritance

Understanding class layers

To improve the reuse of rules in your application, understand how Pega Platform
organizes classes into class layers. Because classes define the applicability, or scope, of
a rule instance, knowledge of the different layers of classes and the way that they
inherit from each other is important as you develop applications.

©2023 Pegasystems Inc

 Pega Platform 8.8 55

Framework classes

Framework classes define a common work-processing foundation that you extend and
modify as implementation applications for an organization, division, or organizational
unit. Framework classes belong to the framework layer.

For example, an enterprise that makes auto loans has an auto loan framework
application that contains all of the assets needed for the basic auto loan process. The
enterprise then develops two implementation applications built on the auto loan
framework to meet the specific requirements of its two divisions: a commercial
business line and a personal line.

Using the New Application wizard, you can build a new implementation application and
its implementation classes on an existing framework application. You can reuse some
or all of the case types and data types of the framework application. In your new
implementation application, you can use the Dev Studio landing pages, explorers, rule
forms, and reports to reuse many of the rules and data objects inherited from the built-
on framework layer. For example, while developing a process, you can select
specifications or processes in a framework ruleset for reuse or customization in the
current application.

When you build an implementation application, you can also create a reusable
framework application built on the same framework. You can then extend the
framework application so that it is usable by other implementations that you might
create later. As a best practice, reuse framework rules and create only specialized rules
in your implementation applications. For example, use report definitions in the
framework classes that run with the corresponding implementation classes.

Implementation classes

Implementation classes define the extension, reuse, and specialization of assets in a

framework layer to meet the business requirements of an organization, division, or
organizational unit. For example, you can build two division-level implementations –

©2023 Pegasystems Inc

 Pega Platform 8.8 56

business auto loan and personal auto loan – on an organization's auto loan framework
layer.

Implementation classes belong to the implementation layer. Typically, cases that are
related to application processes are instances of case type classes that belong only to
the implementation layer.

Organization classes

Organization classes contain enterprise-wide data assets and assets that your
application reuses for business logic. Data assets include classes and rules for data
stored in the system, and classes and rules for accessing data in external systems by
using connectors. Business logic assets include standard properties, decision tables,
and service-level agreements.

For example, the auto loans enterprise might want to reuse, on an enterprise-wide
basis, the property for employee serial numbers. By reusing this property, the various
applications across the enterprise that the employees use can consistently rely on the
same serial number property representing the same employee.

Organization classes belong to the organizational layer. In most configurations, your

implementation and framework layers inherit by pattern inheritance from organization
classes.

For relevant training materials about a class structure, see an Enterprise Class Structure
topic on Pega Academy.

• Configuring applications for reuse

• Creating applications
• Creating applications

Understanding class hierarchy and inheritance

To save development time when creating an application, reuse rules by organizing them
into classes, and then creating dependencies between the classes. When you create a

©2023 Pegasystems Inc

 Pega Platform 8.8 57

class hierarchy you define which classes contain other classes, and as a result, you
define how classes reuse or inherit rules.

In Pega Platform, you can create parent classes that contain child classes. Any rules
available in a parent class are also available to the child classes. Because of this, Pega
organizes classes in the following groups:

• The ultimate base class, which Pega Platform provides and identifies by the
keyword @baseclass. The ultimate base class is a root for all other classes.
• Base classes that store the rules that provide basic functionality for processing
cases, such as data elements that record the creator of a case. The most common
base classes include Work-, Data-, and History- classes.
• Classes from other applications, such as industry-specific Pega applications. For
example, you can use a generic application for policy administration as a base for
customizing versions for different policy types.
• Classes that collect rules and data elements that are common at the division and
organization level, such as a class that stores an approval process shared across
an entire IT department.
• Classes that describe a specific case type, such as expense reports or vehicle
insurance claims.

The Records Explorer lists child classes under their parent class.

Careful planning and analysis are important when creating new classes, so that you can
understand their interrelationships and plan their positions in the standard class
hierarchy. Maximizing reuse of standard classes, standard properties, and other
standard rules supports fast development with less effort. You can also provide for
greater reuse of classes by creating class groups. A class group data instance unifies a
set of classes in the PegaRULES database that share a common name structure and
common key structure. All classes that belong to the same class group share one
database table. For more information about class groups, see Working with class
groups.

©2023 Pegasystems Inc

 Pega Platform 8.8 58

Class naming convention

The names of all classes that belong to a common class group start with the class group
name, followed by a hyphen. For example, if you define a class group Work-Object-App-
Task, you can name the child classes in this class group Work-Object-App-Task-Ordering,
Work-Object-App-Task-Shipping, and Work-Object-App-Task-Billing.

For more information about class names, see Naming conventions for classes.

Class inheritance

Classes can inherit rules in the following ways:

Pattern inheritance
A class inherits characteristics automatically through the class name structure.
Pega Platform uses a multi-level class hierarchy of Organization (Org), Division
(Div), Unit and Class group to organize application assets. During rule resolution,
the system looks for rules from the bottom of the class hierarchy (the most
specific class), to the top, (the ultimate base class). The system can reuse rules
only within one application.
Directed inheritance
A class inherits characteristics directly from a specified parent class, regardless of
any defined pattern inheritance. You typically apply directed inheritance to
reusing standardPega Platform rules and rules from other applications outside
the business class hierarchy.

For learning materials about inheritance patterns, see a Rule reuse through inheritance
topic on Pega Academy.

For learning materials about classes, see a Classes and class hierarchy topic on Pega
Academy.

Related tasks

• Creating rulesets

©2023 Pegasystems Inc

 Pega Platform 8.8 59

• Creating branch rulesets

• Categorizing a ruleset

Understanding external classes

For improved application development, understand how your application uses classes
that correspond to tables in an external relational database, rather than to a table or
view in the PegaRULES database. By reusing external classes, you can include resources
from outside the Pega Platform database in your application.

No inheritance or rule resolution applies to external classes, even if the class name
contains a hyphen. Because each external class has an associated database table Data-
Admin-DB-Table instance, it cannot be part of a class group.

The following methods can operate on an instance of an external class:

• Obj-Browse
• Obj-Open
• Obj-Open-by-Handle
• Obj-Delete
• Obj-Refresh-and-Lock
• Obj-Save
• Obj-Save-Cancel
• Commit
• Rollback

You cannot create Declare Index rules that have an external class as the Applies To key
part. However, Rule-Declare-Expressions rules, Rule-Obj-Validate rules, and Rule-Declare-
Trigger rules operate on clipboard property values for external classes.

External classes do not contain the @baseclass.pzInsKey and @baseclass.pxObjClass

properties, which are present in every internal class. In some cases, no single property
in the external class can serve as a unique handle. To support the Obj-Open-by-Handle

©2023 Pegasystems Inc

 Pega Platform 8.8 60

method with external classes, Pega Platform assembles a substitute string from the key
columns of the table.

In certain cases, you can improve the performance of database insert, delete, and
update operations for external classes through the optional batchUpdates setting in
the prconfig.xml file or dynamic system settings.

System messages sometimes refer to external classes as "Obj-External"; however, Pega

Platform does not have an Obj-External method.

• Creating classes
• Organizing rules into rulesets

Creating classes
For improved development and maintenance of your application, organize the rules
and other objects in your application into classes. By creating classes, you define
collections of objects that are available to other classes or to instances of the class. You
can reuse classes, and as a result reduce both development time and costs.

1. In the header of Dev Studio, click Create > SysAdmin > Class.
2. In the Class record configuration section, in the Label field, enter a short
description for the class that you want to create.
3. In the Class name field, enter a unique name for your class.

A class name can have the maximum length of 56 characters.

To show the relationship between classes, use a hyphen in the class name in
which the first name is a parent class.

For example:

To create a Jobtitles class that derives from an HR class, enter HR-

Jobtitles.

©2023 Pegasystems Inc

 Pega Platform 8.8 61

Note: Avoid using names that start with Code-, System-, and
History-, because the system creates these classes automatically.

4. In the Context section, select an application layer in which to store your class.
5. In the Add to ruleset list, select a ruleset in which to store your class.
6. Optional: To override the default work item that your application associates with
this class, in the Work item to associate field, press the Down arrow key, and then
select a work item.
For more information about default work items, see Setting your current work
item.
7. Click Create and open.
8. On the General tab of the class form, select a class type, and then define the class
settings for your new class:

Choices Actions

Define the settings for an abstract a. In the Select class type list, select
class Abstract.
b. In the Settings section, in the
Created in version field, enter the
ruleset version that applies to this
class, and then go to step 10.
Abstract classes have no instances
in a database.

Define the settings for a concrete class a. In the Select class type list, select
Concrete.
b. In the Settings section, in the
Created in version field, enter the
ruleset version that applies to this
class, and then go to step 9.

©2023 Pegasystems Inc

 Pega Platform 8.8 62

Choices Actions

Concrete classes have instances in a

database. For more information, see
Class keys.

9. Define the class group settings of a concrete class:

Choices Actions

Create a class group a. In the This class list, select The class
is a class group.

Result:

The Class group field

autopopulates with the class
name.

b. Optional: To encrypt the Storage

Stream of each instance of this
concrete class when saved to the
PegaRULES database, and to decrypt
the Storage Stream when an
instance is retrieved from the
database, select the Encrypt BLOB
check box.
For more information, see
Encrypting the storage stream
(BLOB).
c. Optional: To define key parts of the
class, in the Keys section, provide a
key name and a caption.
For more information about class
keys, see Class keys.

©2023 Pegasystems Inc

 Pega Platform 8.8 63

Choices Actions

d. Optional: If you provide only one

key, to ensure that instances of this
class are unique, and to
automatically supply a globally
unique value for further new
instances, select the Automatically
generate a unique ID for records of
this type check box.

Define the settings for a class that a. In the This class list, select does not
does not belong to a class group belong to a class group.
b. Optional: To encrypt the Storage
Stream of each instance of this
concrete class when saved to the
PegaRULES database, and to decrypt
the Storage Stream when an
instance is retrieved from the
database, select the Encrypt BLOB
check box.
For more information, see
Encrypting the storage stream
(BLOB).
c. Optional: To define the key parts of
the class, in the Keys section,
provide a key name and a caption.
For more information about class
keys, see Creating classes.

Define the settings for a class that a. In the This class list, select belongs
belongs to a class group to a class group.

©2023 Pegasystems Inc

 Pega Platform 8.8 64

Choices Actions

b. In the Class group field, enter a class

group name that you want to
include this class.
c. Optional: To encrypt the Storage
Stream of each instance of this
concrete class when saved to the
PegaRULES database, and to decrypt
the Storage Stream when an
instance is retrieved from the
database, select the Encrypt BLOB
check box.
For more information, see
Encrypting the storage stream
(BLOB).

10. In the Class inheritance section, define how the class that you create inherits rules
from superclasses:
a. Optional: To use pattern inheritance before direct inheritance when the
system finds rules at run time, select the Find by name first (Pattern) check
box.
Pattern inheritance searches in superclasses based on prefixes to class
names that end in a hyphen.
b. In the Parent Class (Directed) field, enter the class name of the immediate
parent of your new class:

For concrete classes that are class groups, enter Work- or a class that
inherits from the Work- base class, or enter History-Work- or a class that
inherits from the History-Work- class, if you create a class to hold the history
of work items.

©2023 Pegasystems Inc

 Pega Platform 8.8 65

If you enter the longest possible prefix for your new class ending in a
hyphen, you can select or clear the Find by name first (Pattern) check box,
with no difference in rule resolution behavior or results. For example, if you
create a Work-Object-Mortgage class and the parent class is Work-Object-,
the system performs the same search regardless of the check box setting.
Avoid using System- and Code- base classes, because these classes are
reserved.

Note: During rule resolution, the system considers only direct

parent classes. For example, class C inherits from class B, and B
inherits from A, but C does not inherit from A.

11. Click Save.

12. Optional: If you create a concrete class, check the class connection with the
database by clicking Test connection.

Note: For the test connection to work, ensure that the JDBC JAR file for
the database platform is present and included in the classpath, and that
the prconfig.xml file contains an entry for the database driver. For
example, <env name="database/drivers"
value="org.postgresql.Driver" />

Result:

A window that contains the test results opens. The results include whether
the class is abstract or concrete, and the database and database table if the
class is concrete.

Related concepts

©2023 Pegasystems Inc

 Pega Platform 8.8 66

• Organizing rules into rulesets

Related tasks

• Creating a ruleset and a ruleset version

• Creating branch rulesets
• Deleting a rule

Naming conventions for classes

Unified naming standards for classes help you manage your resources in a logical and
efficient way. You can avoid duplicating your content, maximize efficiency, and speed
up application development by sharing resources between multiple classes or class
layers.For example, you can create class names that support class inheritance, so that
you can reuse resources across different classes. When you name a class
ReviewRequest-LoanRequest, you indicate that a new class LoanRequest inherits
resources from the ReviewRequest class.
When you name classes, consider the following guidelines:

• Use a noun for a class name, for example Customer or Address to distinguish
classes from actions and processes. For better readability, capitalize the first letter
of each word, for example, CustomerAddress.
• Ensure that your class name is descriptive and clearly conveys the purpose of the
class.
• Avoid using acronyms and abbreviations that are difficult to decode. The
exception are common acronyms, such as HTML.
• Avoid including underscores (_) in class names.
• Pega Platform provides a set of base classes that includes the Work-, History-, and
Data- classes. Create new classes only under the organization base class, for
example, UPlusTelco-.
• The system displays labels for class names on some of the forms, worklists,
reports, and other areas of an application. The system also displays a short
description for the class. Therefore, use class names that are self-explanatory and

©2023 Pegasystems Inc

 Pega Platform 8.8 67

reflect the purpose of the work. Avoid using class names that reflect a status or
action, instead of a unit of work.
• Choose class names that support pattern inheritance, as well as directed
inheritance. For more information about class inheritance, see Understanding
class hierarchy and inheritance.
• To distinguish hierarchy position and inheritance, use class names that visually
reflect pattern inheritance. For subclasses, include the names of all parent classes,
including your top-level class, separated by dashes. For example, if the parent
class YourCoLoan-Request includes child classes for mortgage and car loan
applications, name the child classes YourCoLoan-Request-Mortgage and
YourCoLoan-Request-Auto.
• Name related objects with consistent prefixes, so that you can quickly locate
similar classes in an alphabetical list.
• Use the same naming conventions for class groups as for classes.

• Organizing rules into rulesets

• Creating rulesets
• Understanding class layers
• Creating classes

Class keys

When you define concrete classes, you can add keys to identify the classes. You can add
the keys when you create a class, or you can update the keys later.

Every instance of a concrete class includes a key formed from the value of the
properties that the class contains. The value is unique within the class or class group.
For example, your system can contain only one instance of the Data-Admin-Operator-ID
class with an ID value of SampleID. Similarly, your system can contain only one HTML
fragment rule named MyFragment in the same ruleset and version.

The properties that form the key might apply to the concrete class itself, or to a parent
class. For rule instances, the system appends the ruleset and version as part of the
internal key.

©2023 Pegasystems Inc

 Pega Platform 8.8 68

Pega Platform looks in three places to learn which property values to connect to, and in
what order, to form the unique key. The system assembles keys the first time it saves
an instance:

• For a concrete class that does not belong to a class group, the system first
examines the Keys array of the Class form. If this array is not empty, it forms a key
by connecting the values of the properties identified in that array.
• If the Keys array of a class is empty, the system uses class inheritance to locate a
superclass for which the Keys array on the Class form is not blank. When the
system finds such a class, it connects the values of the properties in that Keys
array, and forms the key.
• For a concrete class that does belong to a class group, the system forms a key
based on properties in the Keys array of the Class Group form. As a result, the
system ignores any information in the Keys array of the Class form.

When you add keys to a class, consider the following factors:

• The system creates both a new class and single value properties of the Text type
when you enter the property names into the Keys array, before you save the Class
form for the first time. If you want to apply one or more already-defined
properties as key properties to a super class of this class, enter the already-
defined properties after you save the Class form.
• For concrete classes derived from the Log- base class, the property
pxCreateDateTime is usually the final or only key part. In some high-volume
systems, two log events might occur in the same millisecond. If this can occur in
your Log- class, choose additional properties to ensure uniqueness.
• For concrete classes derived from the Index- base class, enter the properties
pxInsIndexedKey, pxIndexCount, and pxIndexPurpose in that order. Avoid using any
other properties in the key.
• For external classes, use of properties with a Type value of Date, Time, DateTime, or
Double as key parts might introduce rounding or uniqueness issues. Review the
data representation on the external database that you use, to confirm that it
maps one-to-one with the Pega Platform representation.

©2023 Pegasystems Inc

 Pega Platform 8.8 69

• If two or more properties form the key, the order of rows in the Keys array is
significant. Consider which order is likely to produce a natural or frequently
presented sort order in reporting or searching.

Related concepts

• Understanding class hierarchy and inheritance

• Rule resolution

Related tasks

• Creating rulesets
• Deleting a rule

General tab on the Class form

Use the General tab to define the class inheritance and database access.

Note: After you save this form, your entries for many fields are permanently
set and you cannot change them later. However, the Keys array is an
exception. If you save the form with the Keys array blank, you can update the
Class form later and specify the Keys array to reference properties that are
defined to apply to this class.

How the system forms key values from the properties in the Keys
array

Every object saved to the PegaRULES database — that is, every instance of a concrete
class — must have a key formed from the value of properties that is unique within the
class or class group.

©2023 Pegasystems Inc

 Pega Platform 8.8 70

For example, your system cannot contain two instances of the Data-Admin-Operator-ID
class with an ID value of smith@smith.com. Similarly, your system cannot contain two
HTML fragment rules named MyFragment in the same ruleset and version.

The properties that form the key may apply to the concrete class itself or to a parent
class. (For rule instances, the ruleset and version are appended as part of the internal
key.)

Pega Platform looks in three places to learn which property values, in what order, to
concatenate to form the unique key. The system assembles keys the first time it saves
an instance:

• For a concrete class that does not belong to a class group, the system first
examines the Keys array of the Class form. If this array is not empty, it forms a key
by concatenating values of the properties identified in that array.
• If the Keys array of this class is empty, the system uses class inheritance to locate
a superclass (an ancestor) for which the Keys array on this tab of the Class form is
not blank. When such as class is found, it concatenates the values of the
properties in that Keys array to form the key.
• For a concrete class that does belong to a class group, the system forms a key
based on properties in the Keys array of the Class Group form. As a result, any
information in the Keys array of the Class form is ignored.

Completing the Settings fields

The appearance of the General tab changes depending on whether you enter a class
group, keys, or neither. You cannot enter both a class group and keys. If you enter a
class group, Pega Platform uses keys defined in the class group.

When you save the Class form, most of the choices you made become permanent. For
example, you cannot later select or clear the Find by name first (Pattern)? check box to
use, and you cannot change properties entered in the Keys array.

©2023 Pegasystems Inc

 Pega Platform 8.8 71

Field Description

Select Indicate whether this class is to be abstract

or concrete. Both abstract and concrete
classes can have subclasses.

If this class is to have persistent instances,

select Concrete . (You cannot select
Concrete if the class name ends with a
hyphen.)

Otherwise select Abstract .

Created in Version Identify the ruleset version number that

applies to this class. The Archive tools
depend on the version you enter here. The
Export Archive tool includes this class
instance if you export this ruleset version or
a higher-numbered version.

However, version information in class rules is

not used for rule resolution. You cannot
define multiple class rules with the same
class name but different versions.

Complete this field when first creating a new

class (with New or Save as). Alter this field
later in rare circumstances only.

This Class Select one:

• belongs to a class group to

indicate that: (1) the key format of this
class is identical to the key format of
another class, (2) an existing class

©2023 Pegasystems Inc

 Pega Platform 8.8 72

Field Description

group named identically to the other

class exists, and (3) you want to store
instances of this class in the same table
as instances of other member classes.
Typically, choose this option for a
concrete class derived from the Work -
base class.
• does not belong to a class
group to indicate that database
storage of this class is determined by
the class inheritance and database
table data instances.
• is a class group to have Pega
Platform create a class group data
instance with a name identical to the
name of this class, This allows other
classes to share a database table
associated with instances of this class.

If this concrete class is derived from the

Work- base class or the History-Work- class,
select:

• is a class group or
• belongs to a class group .

Note: Concrete classes created in

releases prior to PRPC Version 6.2
might not conform to this
restriction.

©2023 Pegasystems Inc

 Pega Platform 8.8 73

Field Description

As a best practice, choose belongs to a

class group for any concrete class that is
derived (according to pattern inheritance
from a class that has This class set to is a
class group . Otherwise, warning message
may appear when you save the Class form.
Although possible, avoid creating Database
Table mappings for subclasses of a class
group that differ from the Database Table for
the entire class group.

If you create a class is derived from the Work

- base class, and you selected is a class
group , review the Description for this class
carefully; the Description text is visible to
application users. See More about Class
rules.

For an external class created through the

External Data Table wizard, the initial value is
does not belong to a class group .
Do not change this value.

Encrypt BLOB Select to cause Pega Platform to encrypt the

Storage Stream of each instance of this
concrete class when saved to the PegaRULES
database, and to decrypt the Storage Stream
when an instance is retrieved from the
database.

This check box appears only for concrete

classes. It affects only instances of exactly

©2023 Pegasystems Inc

 Pega Platform 8.8 74

Field Description

this class, not instances of any subclasses of

this class.

Note: Determine whether you

application is to use this feature
early during the development
project. You cannot select or clear
this check box if the database
already contains instances of the
class.

Additional configuration is required to set up

this capability. See Storage Stream
encryption of selected classes.

About the Class Group field

This field appears only when is a class group or belongs to a class group
is selected in the This class field. Confirm that the class group identified is the one
expected.

Field Description

Class Group Optional. If you selected belongs to a

class group , select a class group (an
instance of the Data-Admin-DB-ClassGroup
class) from the list. A class group — a data
instance — has the same name as its first or
defining container class.

©2023 Pegasystems Inc

 Pega Platform 8.8 75

Field Description

The name of the class group you choose

must match an initial portion of the class
name.

Choose this option when defining one or

several concrete classes that define types of
work items to be stored and processed as
part of a single application, or the
corresponding class derived from History-
Work-.

If you enter a class group, leave the Keys

array empty. In this case, the class group
instance defines a common key structure
used by all associated classes.

Completing the Keys fields

The keys array appears only for concrete classes that either define a class group or that
are do not belong to a class group.

If the Keys array appears, in many cases, you can leave it blank, at least when you first
save the Class form:

• To create new Single Value properties of type Text with this class as the
Applies To key part, enter the property names into the Keys array before you first
save the Class form. When you save the form, the system creates both the new
class and properties.
• To use one or more properties already defined to apply to a superclass of this
class as key properties, do not enter them before you first save the Class form.
Save the Class form once, and then use SmartPrompt to select the properties that
form the key.

©2023 Pegasystems Inc

 Pega Platform 8.8 76

• For concrete classes derived from the Log- base class, the property
pxCreateDateTime is usually the final (or only) key part. In some high-volume
systems, two log events may occur in the same millisecond. If this can occur in
your Log- class, choose additional properties to ensure uniqueness.
• For concrete classes derived from the Index- base class, enter the properties
pxInsIndexedKey, pxIndexCount, and pxIndexPurpose in that order. No other
properties can appear in the key.
• For external classes, use of properties with a Type value of Date , Time ,
DateTime , or Double as key parts is permitted, but may introduce rounding or
uniqueness issues. Review the data representation on the external database to
confirm that it maps one-to-one with the Pega Platform representation.

Field Description

Keys If two or more properties are to form the key,

the order of rows in this array is significant.
Consider which order is likely to produce a
natural or frequently presented sort order in
reporting or searching.

For example, consider a class named Data-

County, with a key formed from a county
name (such as Suffolk, for Suffolk county)
and state code (such as MA for
Massachusetts). Assuming that reporting
requirements present county information
within state, a natural order for the two key
parts is state followed by county.

Name Optional. Leave blank if the concrete class is

a subclass of a superclass that corresponds
to a class group. Also, leave blank if a parent
(or higher superclass) of this class is concrete

©2023 Pegasystems Inc

 Pega Platform 8.8 77

Field Description

and the key structure of this class is to be the

same as the key structure of the parent.

Identify the property or properties that

together define a unique key for objects of
this class. If the property or properties that
are to form the key are not yet defined, you
can create them automatically the first time
you save the Class form by entering a name
here.

If the properties that are to make up the key

are already defined (in a superclass), do not
enter them initially. Save the Class form
once, then use SmartPrompt to select them
as rows in the Keys array, and then resave
the Class form.

Typically, the key of an object also

determines how it is identified when locked.
In the unusual case that a different key
structure is needed, you can define a
separate lock string on the Locking tab.

Caption Optional. For concrete classes derived from

Rule- or Data- for which a Rule-File-Form is
present, this text appears as field labels in
the New dialog box.

In other cases, you can enter text to

document why you chose this property to be

©2023 Pegasystems Inc

 Pega Platform 8.8 78

Field Description

part of the key; the information you enter

appears only in this field.

Automatically generate a unique ID for This checkbox appears when you have
records of this type entered one key field. If you want instances
of this class to be unique using this one field,
and you want the system to automatically
supply a globally unique value for new
instances, select this check box. Selecting
this check box also changes the key name to
pyGUID.

Completing the Rule Instances of this class fields

These four check boxes appear only for concrete classes derived from the Rule- base
class, with a few exceptions. They determine which aspects of the full rule resolution
algorithm the system uses to find rules of the new rule type. See How the system finds
rules through rule resolution.

Field Description

Allow multiple versions with the same key When selected causes the system to allow
values? (rule resolution) multiple rules of this rule type to have the
same name, distinguished by ruleset or
ruleset version. If this check box is selected,
at run time Pega Platform uses the ruleset
list part of the rule resolution algorithm for
this class to select a rule at run time.

Allow selection of rules based on property When selected, causes the system to allow
values? (circumstance-qualified) rules of this rule type to have circumstance-
based qualifications. If this check box is
selected, at run time Pega Platform uses

©2023 Pegasystems Inc

 Pega Platform 8.8 79

Field Description

circumstance-based processing at run time

to select a rule, and these fields appear on
the Save As form. See circumstance.

This field appears only when the Allow

multiple versions field is selected.

Allow rules that are valid only for a certain When selected, causes the system to allow
period of time? (date range availability) rules of this rule type to have time-based
qualifications. If this check box is selected,
Pega Platform uses time-based processing at
run time to select a rule, and these fields
appear on the Save As form. See time-based
rules.

This field appears only when the Allow

multiple versions field is selected.

Use class-based-inheritance to arrive at the When selected, causes the system to cause
correct rule to execute? the system to search up the class inheritance
structure (using both pattern and directed
inheritance) to find rules of this rule type. If
this check box is not selected, at run time
Pega Platform expects to find the rule in the
current class only, not by searching through
super-classes.

Completing the Class Inheritance fields

Indicate how this class inherits rules from super classes.

©2023 Pegasystems Inc

 Pega Platform 8.8 80

Field Description

Find by name first (Pattern)? Select to cause the system to use pattern
inheritance before it uses directed
inheritance when finding rules at run time.
Pattern inheritance searches superclasses
based on prefixes of the class name that end
in a hyphen.

Clear this check box to bypass pattern

inheritance. Directed inheritance always
occurs for all rule types with an Applies To
key part.

If you selected belongs to a class

group , this check box is selected.

After you save a Class form, you cannot

change this setting.

Parent class (Directed) Identify the class that is to be the immediate

parent of this class:

• If you don't select the Find by name

first (Pattern)? check box, at run time as
part of rule resolution processing, the
system searches the parent class and
its parent and so on when it cannot find
a rule in the current class.
• If you select the Find by name first
(Pattern)? check box, the system during
rule resolution searches classes with
derived class names before it searches
the parent class identified in this field.

©2023 Pegasystems Inc

 Pega Platform 8.8 81

Field Description

If you selected is a class group in the

This class field, enter Work- or a class that is
derived from the Work- base class here. (Or,
enter History-Work- or a class that is derived
from History-Work-, if you create a class to
hold the history of work items. Such History-
Work- classes are ordinarily created
automatically.)

If you enter the longest possible prefix of this

class ending in a hyphen, you can select or
clear the Find by name first (Pattern)? check
box, with no difference in rule resolution
behavior or results. For example, if this class
is named Work-Object-Mortgage and the
parent class is to be Work-Object-, Pega
Platform performs the same search
regardless of the check box setting.

CAUTION: Do not assume that the

"inherits from" relationship is
transitive. Because only one Parent
class to inherit from (Directed)
value is used by a rule resolution, it
is possible that class C inherits
from class B, and B inherits from A,
but C does not inherit from A.

Note: You cannot create a class

derived from the Code- or System-

©2023 Pegasystems Inc

 Pega Platform 8.8 82

Field Description

base classes. These base classes

are reserved.

Testing the class-to-database table mapping

For a concrete class, you can test the database connection and learn the table
structure.

Test Connection After you save the Class form, click to

confirm that the database instance ( Data-
Admin-DB-Name ) and database table
instance ( Data-Admin-DB-Table ) are working
as intended. The test confirms that Pega
Platform can access the database and
displays the database table that will contain
instances of this class.

Results appear in a new window, identifying

the database and database table that
correspond to this concrete class, and
whether the class is an internal or external
class.

This button appears only for concrete

classes.

Note: For the test connection to

work, the JDBC JAR file for the
database platform must be
present and included in the
classpath and the prconfig.xml

©2023 Pegasystems Inc

 Pega Platform 8.8 83

file must contain an entry for the

database driver. For example:

<env name="database/drivers"
value="org.postgresql.Driver" />

How to include properties in a class as key parts of that class

As you complete the Key Name fields while adding a class, you can only reference
existing properties. If a key part for your new class is a property that will apply to the
new class, you cannot create the property until after you create and save the class rule.

Take these steps to work around this circular situation:

1. Save the class rule with the Keys array empty; no keys defined.
2. Define properties that are to form the keys in the class in the normal way.
3. Open the class rule again, and enter the key properties into the Keys array of the
General tab.
4. Save the class rule again.

• Organizing rules into classes

Locking tab on the Class form

Information on this tab is used only for concrete classes that do not belong to a class
group.

Select the Allow Locking box to cause the system to lock open instances of the class,
that is, instances copied from the database into the clipboard using the Obj-Open
method or similar methods.

For concrete classes that do belong to a class group, leave this tab blank. The Lock field
on the Class Group form controls locking for all the classes in the group. See Concepts
— Understanding object locking.

©2023 Pegasystems Inc

 Pega Platform 8.8 84

Field Description

Keys

Key Name Optional. Leave this array blank in all but

rare circumstances. If this field is blank, the
Keys properties from the General tab of this
form is used to define a lock string.

In unusual situations, you can define a non-

standard lock for the class by listing here the
properties that together define the lock key.
The value of these properties (rather than
the properties on the General tab) are
concatenated to form a lock key for the
instance. The resulting value may at runtime
apply to multiple open objects, locking not
only this object but all other open objects
(even objects of other classes) with the same
completed lock key value.

Key Caption Optional. Not used.

Locking

Allow Locking For concrete classes, select this box except in

rare situations. Select to allow the system to
lock open instances of the class when the
Obj-Open or Obj-Open-By-Handle method
specifies locking.

However, for concrete classes derived from

the Rule- base class, leave cleared. To restrict
updates to individual rules to one developer
at a time, use rule checkout (by updating the

©2023 Pegasystems Inc

 Pega Platform 8.8 85

Field Description

RuleSet to allow checkout, and updating the

Operator ID to enable checkout), not locks.

If this class is part of a class group, the Lock

field on the class group form supersedes this
Allow Locking? value.

If selected, a user cannot save or delete an

instance within the scope of this class group
unless that user holds a lock on the object.
Typically, activities acquire locks when they
open an instance to the clipboard.

Note: If Allow locking? is selected,

then when you use the Obj-Open,
Obj-Open-by-Handle or Obj-
Refresh-and-Lock method in an
activity to open an instance within
the scope of this class group (with
intent to update and save the
instance), select the Lock check
box parameter for the method.

• Object locking

• Organizing rules into classes

©2023 Pegasystems Inc

 Pega Platform 8.8 86

Object locking
Locks are implemented separately from the locking mechanism supplied by the
database software (such as Oracle) that supports the PegaRULES database. Locks are
exclusive to one thread, and operate system-wide in a multinode system.

Basics

A requestor can lock an open instance if all of the following are true:

• The instance belongs to a concrete class that has Allow Locking selected in the
class rule.

AND

• The instance has ever been saved and committed to the PegaRULES database.
• The requestor has an access role that conveys the privilege needed.

Properties identified on the Locking tab of the Class rule form together define the lock
identity. (If the Locking tab contains no property names, the properties that form a lock
definition are the same as those that form the external key that is defined on the
General tab.) All classes in one class group (which corresponds to one database table)
have the same properties in the lock definition.

Viewing locks — Standard reports

To view locks held by your own requestor session, select Configure > Case
Management > Tools > Work Admin > My Locks.

To view all locks held by any requestor, select Configure > Case Management > Tools >
Work Admin All Locks, and drill down to identify the details of the locked object. Hold
the mouse pointer over a row of the drill-down detail to identify the Operator ID of the
requestor holding the lock.

©2023 Pegasystems Inc

 Pega Platform 8.8 87

These two reports present instances of the System-Locks class, corresponding to the
pr_sys_locks table of the PegaRULES database.

Viewing locks — In an activity or flow

Locks are acquired by activities, using one of three methods: Obj-Open, Obj-Open-by-
Handle, or Obj-Refresh-and-Lock. Optionally, each of these methods can store detailed
results in a page of class System-Locks. If a method failed to acquire a lock because the
object is already locked, information on this page identifies the current requestor
session that holds the lock. By convention, this page is named LockInfo in standard
rules.

As a debugging aid, the standard section System-Locks.LockInfo and the standard

harness Work-.LockInfo can present information from that page to an application user.
The LockInfo page contains these properties:

• pxExpireDateTime
• pxLockHandle
• pxOwnerID
• pxUpdateOperator
• pxCreateDateTime

The lock string

A lock string uniquely identifies a lock. For instances that belong to classes not
associated with a class group, the text string consists of the class name concatenated
with the key parts of the object (determined on the Keys area of the Basics tab of the
Class form, or the Locking tab of the Class form).

For an object that is within the scope of a class group, the lock string consists of the
class group name concatenated with the value of the key properties identified on the
Keys tab of the Class Group form. For example, for the Sample Work application, the
class group is named PegaSample and work items in the PegaSample-Task class are
identified with a W- prefix. The lock string for work item W-43 is thus:

©2023 Pegasystems Inc

 Pega Platform 8.8 88

PEGASAMPLE-TASK W-43

Expired ("soft") locks

Generally, a thread that acquires a lock retains it until the instance is saved again with a
Commit method (which may complete an Obj-Save or Obj-Delete method). However the
system automatically expires locks held longer than a specified timeout period. You can
change the default timeout interval of 30 minutes to a longer or shorter period. This
value is stored in the Data-Admin-System data instance.

An expired or "soft" lock remains held by a requestor session until the session releases
it or until the requestor session ends, but a soft lock can be stolen — broken and
acquired — by another requestor who opens the instance. In that case, any updates by
the first user that are not committed are lost.

Releasing locks

Except as described below, a requestor can only release locks held by its own session. A
Commit method releases all the locks held by a requestor Thread that were acquired
with the ReleaseOnCommit box checked when the object was opened.

When a user signs off, any locks held by that requestor are released.

In contrast, locks are not released when a user closes a browser session by clicking the
Windows close box (rather than by logging out). The locks may be needed by another
Thread of the same operator, or by another operator or process. Encourage users to
log off through a button or link rather than closing the window.

Releasing locks of other sessions

Lock information is held in the memory of each node, rather than in the database, for
improved performance. However, even in a multinode system, a requestor can force
the release of locks held by any session with the same Operator ID and same user
name ( pyUserName ) through the PublicAPI method:

©2023 Pegasystems Inc

 Pega Platform 8.8 89

LockManager.unlock(StringMap, boolean)

This method communicates through the system pulse across all nodes. On each node,
the system searches existing requestors (including passivated ones) using the supplied
requestor ID. If a session is found, the system checks that the user names
( pyUserName ) also match before attempting to terminate the other session. If a
session is found that matches the requestor ID, but the user names do not match, the
system generates a SECU007 security alert and lists the corresponding requestor ID
and user name in the logs.

Note: You cannot release a lock that is held by another user, even if that user
is no longer on the system. Instead, wait for the lock to timeout and become
“soft” and then steal the lock. Otherwise, the lock is purged after the default
timeout interval.

Testing for locks

To test whether a work item is locked, an activity can call the standard activity
Work-.WorkLock, which tries to lock the work item. If it fails to acquire a lock, the
SuccessInfo parameter is negative, indicating that the work item is already locked.
The FailureInfo parameter provides additional detail.

To test whether a lock is held on a page already on your own clipboard, call the function
rule isPageLocked(tools, pagename).

To test whether an object other than a work item is locked, use one of several methods
in the PublicAPI LockManagerInterface.

Debugging

To add detailed lock manager information to the Pega log, set the Logging Level
Settings tool with this category to Debug :

©2023 Pegasystems Inc

 Pega Platform 8.8 90

com.pega.pegarules.engine.database.LockManagerImpl

To trace locking events from the application, add locking to the list of event types
tracked by Tracer:

1. Open Tracer.
2. In the Settings tab, Event Types section, select Locking.

Advanced tab on the Class form

The Advanced tab is only meaningful for concrete classes derived from the Rule-, Data-,
or Work- class. Use the fields on this tab to control advanced settings such as class
deprecation and ruleset restrictions.

Category

Select a rule category to control where instances of this class appear in the Application
Explorer and Records Explorer. This list is populated by field values with Rule-Obj-Class
and pyCategory as the key parts. You can define additional field values with these key
parts to customize rule categories used in explorers.

Rule form

Use the fields in this section to define the basic rule form structure for instances of this
class:

• Type – Select the Harness option. The Form option is deprecated.

• Name – Type the name of a harness that contains the sections, layouts, and other
components users see when they interact with instances of this class. The applies
to key part of the harness must be this class.

Primary rule assembly

The fields in this section are reserved for custom Rule- descendants that use rules
assembly:

©2023 Pegasystems Inc

 Pega Platform 8.8 91

• Primary Aspect – Select an interface or aspect. This list is populated by public

methods defined in com.pega.pegarules.pub.runtime.PublicAPI .
• Primary Implementation Class – Type the name of a Java class that contains the
rules assembly logic for this class.

Secondary rule assembly

Leave fields in this section blank unless you are creating a custom Rule- descendant that
requires rules assembly for embedded rule types.

Java wrapper

Fields in this section are reserved for class rules generated by the Connector and
Metadata wizard. When JavaBeans are imported, a Java wrapper class is created that
enables the clipboard to access instances of the JavaBean. The name of this Java
wrapper appears in the Wrapper Name field.

For more information, review the Pega Community article Working with the Java Pages
Feature.

Full text search

Select Exclude this class from search to exclude instances of this exact class (not
descendants) from full text search results. This is helpful in systems where a large
number of work objects exist and indexing is enabled. You can eliminate the processing
and space required to index these items.

If the class has entries that have already been indexed, you must remove the the index
from the file system, then rebuild the search index from scratch to remove those
entries from the index.

Note: This option applies only to concrete classes derived from the Work-,
Rule-, or Data- class. As a best practice, do not check this box for Rule- classes.

©2023 Pegasystems Inc

 Pega Platform 8.8 92

Deprecate

Check the box in this section to deprecate all instances of this class and block users
from creating new instances. As a best practice, add documentation in the Usage field
of the History tab. You see this documentation in the form of a warning when you open
or reference an instance of the deprecated class.

Note: Only classes with the Does not belong to a class group option selected
can be deprecated.

Users are warned when they open the class rule form or any instance of the class. The
warning text is populated by the Usage field on the class rule form's History tab. For
example:

The rule type Hierarchy is deprecated and should no longer be used. Please use
navigation rules for tree configuration instead.

You cannot create any new instances of a deprecated class. If you save as the class, the
Deprecate this class type option remains selected.

Deprecated classes in Pega- rulesets are excluded from:

• Search results
• Application Explorer results
• Top-level and right click Create menus in Dev Studio explorers
• Lists launched from the Records Explorer

You can find and view a deprecated class by entering the fully qualified class name in
the Application Explorer and then selecting the Definition right-click option on the class
name.

©2023 Pegasystems Inc

 Pega Platform 8.8 93

Dedicated table

Check the box in this section to create a dedicated database table for instances of this
class. This feature is available only to users with the
@baseclass.pxClassToDbTableOptimization privilege.

Child classes

Check the box in this section to require all classes derived from this class to reside in
the same ruleset as this class.

Ruleset restrictions

Use the list in this section to control which rules can be created with pyClassName set to
this class name. For each row in the list, enter the name of a ruleset in your application
stack. When an operator attempts to create a rule that applies to this class, the system
validates that:

• The ruleset name specified on the create form resides in this list.
• The ruleset version specified on the create form has the ruleset of this class as a
prerequisite.

Note: You cannot add a ruleset to the list that is a prerequisite to the ruleset
version of the class itself. For example, if your class resides in the GAMMA
ruleset, and GAMMA depends on the BETA ruleset, you cannot add BETA to the
list.

• Organizing rules into classes

External Mapping tab on the Class form

The External Mapping tab is used primarily for external classes. External classes are
created by the Connector and Metadata wizard or the Database Class Mappings gadget

©2023 Pegasystems Inc

 Pega Platform 8.8 94

and are linked by a Database Table data instance to a table in a database other than the
PegaRULES database.

Typically, the data on this tab is from one of these two tools, and no manual changes
are required.

Field Description

External Table Column Mapping Optional. Leave blank unless this class is an
external class that represents a table in an
external database (generated by the
Connector and Metadata wizard or the
Database Class Mappings wizard), or you are
replicating scalar embedded properties as
described below.

Fields in this section map the properties

generated for the class rule to the columns
in the external table.

Column Name For generated class rules, the name of a

column in the external table.

Property Name For generated class rules, the name of the

property that represents the table column in
the Column Name field.

Exposing an embedded Single Value property value into a column

For a concrete internal class, you can use this tab to expose match an embedded
Single Value property in a database column.

For example, the embedded property .pyPreferences.pyNavigationPrefs.pyShowTabs

manages whether a user wants to use tabs in his or her developer environment.

©2023 Pegasystems Inc

 Pega Platform 8.8 95

If it were important to use this embedded property as report selection criteria, the
property must correspond to a column. Use these steps to make a (scalar) embedded
property available as a database column.

1. Ask a database administrator to create a new column of the appropriate data type
in the PegaRULES database table that corresponds to the Data-Admin-Operator-ID
table. In this example, the table is pr_operators . The database administrator
created a text column named TABDISPLAY. (You cannot use the Modify Schema
wizard to add this column, because there is no property named TABDISPLAY.)
2. Update the Class rule for the class Data-Admin-Operator-ID. Add a row to the
Column Mapping array on this tab. Enter the new column name TABDISPLAY the
Column Name field and the embedded property reference in the Property Name
field.
3. Thereafter, the system updates the new column TABDISPLAY from the embedded
property .pyPreferences.pyNavigationPrefs.pyShowTabs.pyTabs whenever an
Operator ID data instance is saved. The property
reference .pyPreferences.pyNavigationPrefs.pyShowTabs.pyTabs can be used as
criteria in reports.

This feature provides a direct but limited alternative to creating an Index- class and
maintaining the index through a Declare Index rule, or to replicating the value to a
second (top-level) property using a Declare Expression rule or Declare Trigger rule.

Note:

• In contrast to a Declare Index approach, the embedded property must be

a scalar reference, not an aggregate.
• You can use this approach to expose one fixed scalar value within an
aggregate property, such as pyWorkparty(“Originator”).pyLastName for the
last name of the Originator work party in a work item. In most situations,
however, you want to expose all values, not a single value; the technique
described here does not suffice.

©2023 Pegasystems Inc

 Pega Platform 8.8 96

• Like other schema changes, the database administrator must add the
column in every system that contains the report rules (such as
development, test, and production systems).
• You can update Class rules that belong to foundation rulesets (for
example, the Data-Admin-Operator-ID class).

• Organizing rules into classes

• Viewing database class mappings

Finding the class of a rule

You can view XML data to find the class of a rule. By understanding which class defines
a rule, you can more efficiently use tools such as the Application Explorer and Report
Editor.

1. Open a rule by searching for it or by using the Application Explorer.

2. Click Actions > View XML.
3. Find the first instance of the <pxObjClass> property. This property contains the
rule's object class name. For example, the object class for flow actions is
<pxObjClass>Rule-Obj-FlowAction</pxObjClass>.

• Viewing the XML of a rule

• Finding rules by type

About the Rename a Class wizard

Use the Rename a Class wizard to rename a class and all of its pattern inheritance
dependent classes. In addition you can choose to rename associated objects such as
work- instances, properties, activities, and flows.

©2023 Pegasystems Inc

 Pega Platform 8.8 97

Note: The Rename a Class wizard is designed to assist with refactoring

applications that are in development. It is not intended to be used on a
deployed production application.

The wizard reports any locked rulesets or rules that are checked out before renaming
anything.

In addition to exact matches to the specified class name to be changed, the wizard
identifies references to the current class name in embedded strings, for example in
property names or in embedded Java modules. The wizard displays a listing of these
"inexact" matches, and you can select which to include to be renamed and which to
preserve unchanged.

In particular, use Rename a Class for applications with fewer than a thousand work
objects, or select No on the Work Objects page to drop references in the work objects
to the new class name. After the class is renamed, work items that referenced the
original class can be viewed only as XML.

Starting the wizard

To improve performance, purge all existing work objects from the class before running
the Rename a Class wizard.

Select Configure > System > Refactor > Classes > Rename a Class to start the wizard.
You can return to a previous step using the <<Back button.

Alternatively, select a case type or work pool in the Application Explorer, right-click, and
select Refactor > Rename a Class from the context menu.

No rules are altered by the wizard until you click Next after reviewing additional rules to
be changed on the next-to-last page.

©2023 Pegasystems Inc

 Pega Platform 8.8 98

Resuming the wizard

This wizard creates a work item with prefix pxW- . To find open wizard work items,
select the menu option Dev Studio > Application > Tools > All Wizards .

Prerequisites

You can rename a class if it meets these conditions:

1. The class must be visible in your Access Group.

2. The class may not be one of the standard classes, those in the Pega- rulesets.
3. The original class cannot have Final availability.
4. All rules to be modified must be checked in. (If rules are checked out, check them
in and restart the wizard.)
5. All rules to be modified must belong to unlocked ruleset versions. You must
supply the appropriate password to unlock the locked rules, or you can opt to skip
them for this operation.
6. The new name of the class must not already exist in the system. Class names need
to be unique system-wide, rather than unique within a specific ruleset.
7. You cannot change an abstract class to a concrete class or vice versa. For example,
class A- cannot be renamed to B, and B cannot be renamed to A-.

Results

When complete, the renaming wizard changes your system in the following ways:

1. The class is renamed.

2. Direct and pattern inheritance references the new class name. As a result, there
will be no effect on rule resolution.
3. If the option has been selected, Work- instances associated with the class are
renamed.
4. All properties, activities, flows, and other rules that referenced the original class
now reference the class by the new name.

©2023 Pegasystems Inc

 Pega Platform 8.8 99

5. If the class is a work pool or defines an external data table, the Data-Admin-DB-
Table instance is updated to reflect the new class name.
6. The wizard creates a new History- class for the new class, and it will identify that
the class has been renamed. The History- class for the old class name is deleted.

The old class name is retained until all changes to dependent classes and Work-
instances are completed. Then the original class is deleted. If the system is stopped
while renaming is in progress, you can restart the process by executing the utility from
the beginning.

• Understanding class hierarchy and inheritance

About the Delete a Class wizard

You can use the Delete a Class wizard to remove a class, all of its pattern- inheritance
dependent classes and associated objects such as properties, activities, instances
(including work items, attachments and assignments).

You can only delete classes that meet the following restrictions:

• The class is not in the basic Pega- rulesets that define the Pega Platform.
• The class is in a ruleset listed in your ruleset list.
• The class is not mapped to an external database table.

Starting the wizard

Select Configure > System > Refactor > Classes > Delete a Class to start the wizard.

You can return to a previous step using the <<Back button. No rules are altered by the
wizard until you click Next>> in step 2. For instructions on the forms, see:

• Help 1: Using the Delete a Class wizard.

• Help 2: Display Classes to delete
• Help 3: Display results and search for references
• Help 4: Display references

©2023 Pegasystems Inc

 Pega Platform 8.8 100

• Help 5: End

Resuming the wizard

This tool creates a work item with prefix pxW- . To find open wizard work items, select
the menu option Dev Studio > Application > Tools > All Wizards .

Note:

Checked out rules associated with the class will be deleted. Unlike other rule
management wizards, the Delete a Class wizard does not identify and warn of
checked out rules among those to be deleted.

Deleting a class might render an application inoperative. Always back up the

Pega Platform system before deleting a class.

This wizard can't delete a rule that belongs to a locked ruleset version. Locked
rules will be left in place during the deletion and listed on the summary of
undeleted rules on page 3 of the wizard, Search for References.

The wizard cannot delete a class if it contains one or more rules that have
failed deletion (perhaps because they belong to a locked ruleset version.)
However, all rules that can be deleted will be when you run the wizard. To
complete deleting the class, you must unlock or otherwise make it possible for
the undeleted rules to be deleted and then run the wizard again.

Errors are written to a log. To examine the log, use the Application Explorer to
view instances of the Log-Delete-Class.

Classes related to deleted classes by directed inheritance are not deleted. If

the specified class is a subclass of Work-, all instances are deleted prior to the
deletion of the class.

©2023 Pegasystems Inc

 Pega Platform 8.8 101

Using the Delete a Class wizard - Step 1: Select Class to Delete

Using the Delete a Class wizard —

Step 1: Select Class to Delete

Use the Class drop-down menu to select the class you want to delete.

The drop-down includes classes that are contained the rulesets listed on your ruleset
list. On a large system it may take a while for this list to populate after you click in the
field. Expand the drop-down box and make your selection.

After you have made your selection, click the Next >> button.

Click <<Back to return to the previous step. Click Cancel and then click Done to cancel
the wizard.

About the Delete a Class wizard

Using the Delete a Class wizard - Step 2: Display Classes to Delete

Using the Delete a Class wizard —

Step 2: Display Classes to Delete

This page displays the class and subclasses that will be deleted. The classes and
associated objects such as properties, activities, attachments and assignments will also
be deleted.

Confirm whether you want to delete all the classes listed and then choose one of the
following actions:

• Click Next >> to complete the deletion.

• Click << Back to select another class to delete.
• Click Cancel to exit from the wizard without deleting any classes.

©2023 Pegasystems Inc

 Pega Platform 8.8 102

About the Delete a Class wizard

Using the Delete a Class wizard - Step 3: Display Results

Using the Delete a Class wizard

Step 3: Display results and search for references

This form presents a list of rules that could not be deleted. The Message column
explains why the rule was not deleted and the actions required to delete it.

If there are undeleted rules, the class cannot be deleted. However, all other rules
associated with the class have been deleted. To complete deleting the class, modify the
rules listed so that they can be deleted and then run the wizard on the class again.

Select Reference Search

In the Reference Search drop-down, choose one of the following options to set the
scope over which the wizard is to search for references to the deleted classes:

• Don't search for references

• Search for references in your RuleSet list.
• Search for references in all RuleSets.

In the next step the system searches for references to deleted objects that may need to
be fixed after the deletion is complete. If this search is made over the entire rulebase
on a large system, it can take some time to complete.

When you have reviewed the list of rules and set Reference Search, click Next >> to
complete the deletion and see a list of unresolved references.

About the Delete a Class wizard

Using the Delete a Class wizard - Step 4: Display References

Using the Delete a Class wizard —

©2023 Pegasystems Inc

 Pega Platform 8.8 103

Step 4: Display References

This form provides a list of rules and data which might still reference the deleted class.
The Value column lists the instance that contains the reference, and the other columns
provide the information you need to locate it.

Review this list and correct any invalid references that might interfere with your system.

To review these rules outside the wizard, click Export To Excel to create a spreadsheet
of the currently displayed page, or Export All To Excel to create a spreadsheet of the
entire report.

Click Finish to exit the wizard.

About the Delete a Class wizard

Using the Delete a Class wizard - Step 5: Display References

Using the Delete a Class wizard —

Step 5: End

This form appears when all steps are complete.

Click Finish to exit the wizard.

About the Delete a Class wizard

Rule resolution
Rule resolution is a search algorithm that the system uses to find the best or most
appropriate rule instance to apply to complete processing. By using automated rule
resolution, you can save time and ensure that you implement resources in a way that is
the most efficient in a given scenario.

©2023 Pegasystems Inc

 Pega Platform 8.8 104

For example, you can build an application to review loan requests, and then apply
different approval criteria for standard loans and mortgages. Rule resolution finds rules
that hold appropriate approval criteria based on a loan type that a user selects in the
application. In a different scenario, you can provide an upgraded version of your
application to selected users to gather feedback. At run time, because of rule
resolution, users who upgraded the application see a different UI version than the
users who use your application version before the upgrade.

For relevant training materials, see the Rule resolution module on Pega Academy.

Benefits of rule resolution

The benefits of rule resolution include the following advantages:

• Multiple applications and organizations can share rules. Sharing and reuse are
major benefits of goal-oriented and efficient software development.
• More specific rules that are defined at a higher level can override more general
rules that are defined at a lower level that is closer to the base class. Overriding
rules makes reuse of resources less applicable, but provides flexibility and visibility
to exceptions.
• For greater flexibility, rules can have multiple versions. Rule resolution
automatically determines the most appropriate rule in a given scenario. You do
not need to spend time to manually select a rule.
• One Pega Platform system can host multiple applications, organizations, and
versions of one application with less concern for conflicts or interference.
• If multiple applications depend on a common set of rules, developers can work on
the applications independently without interference if the common rules are
locked.

Classes in rule resolution

Pega Platform defines data in a class hierarchy that follows the object-oriented
paradigm. The hierarchy starts with an ultimate class called @baseclass. Classes are
subdivided into more specialized types of classes. For example, the Requests- class can

©2023 Pegasystems Inc

 Pega Platform 8.8 105

include specialized Requests-Loan- and Requests-Mortgage- classes. Classes can contain

rules that descend from the Rule- base class. Rules can inherit properties from other
rules through class hierarchy. In search for a rule that is defined in a particular class,
the system checks rules that are defined in the class, as well as rules defined in the
ancestors of the class. The system can hold multiple copies of rules, which are different,
and any one of these copies might be useful at run time, depending upon the situation.
Rule resolution is a process by which Pega Platform determines which rule to apply
from the set of candidate rules. Many different rules can apply, so rule resolution
checks all the candidate rules to determine the most accurate way to perform
processing.

The following figure shows a sample class hierarchy that starts with a @baseclass and
then goes from more general to more specialized classes:

Class hierarchy

©2023 Pegasystems Inc

 Pega Platform 8.8 106

For example, in a scenario in which you work with an instance of the UPlusTelco-Auto-
ClaimsEntry class, and the processing requires a Display flow, if the system finds the
Display flow both in UPlusTelco- and UPlusTelco-Auto- classes, it chooses the latter
instance, which is closest to the definition of the class structure of the UPlusTelco-Auto-
ClaimsEntry instance.

Rule resolution begins by selecting all the possible rules with a particular name of a
particular type, such as activities or when rules. For example, at run time, a sample
scenario requires the Approval service-level agreement (SLA) on the UPlusTelco-Process-
Loan class. The system chooses all the Approval SLAs in the UPlusTelco-Process-Loan
class, or the ancestors of the UPlusTelco-Process-Loan class, including rules in different
rulesets, different versions, and different circumstances. The SLA rule in question can
have different definitions in all these places, or the system might find duplicate
definitions in different classes or rulesets. The goal of rule resolution is to select just
one rule that is the most accurate to apply to a given situation.

Rule resolution applies to rule types in classes that inherit from the abstract Rule- base
class. The following list includes examples of instances of rules that derive from the
abstract Rule- base class:

• Case types that belong to the Rule-Obj-CaseType class

• Properties that belong to the Rule-Obj-Property class
• Data pages that belong to the Rule-Declare-Pages class

Rule resolution does not apply to instances of classes that derive from the Work-, Data-,
or any other base class. Those classes typically contain objects to which Pega Platform
refers as records. The following list includes examples of records that derive from these
abstract base classes:

• Operator IDs that belong to the Data-Admin-Operator-ID class

• Email listeners that belong to the Data-Admin-Connect-EmailListener class
• The rule check-in process that belongs to the Work-RuleCheckIn class

©2023 Pegasystems Inc

 Pega Platform 8.8 107

An in-memory rule cache helps the rule resolution process operate faster. If the system
finds an instance, or instances, of the rule in question in the cache, the system accepts
the rule instances in the cache as the candidate rules and skips multiple steps in the
resolution process.

Rule resolution inputs and output

The following list includes the inputs to the rule resolution process:

• The key parts of a rule instance that the rule resolution process targets, such as
the Applies to class and the name of the rule.
• The ruleset list for the user that the system assembles when the user logs in.
• The class hierarchy, which is the structure of classes.

For more information, see Understanding class hierarchy and inheritance.

• The access roles and privileges of the user, determined by the access group that
the user has.
• Security and access control rules, such role access to object rules and privileges.
• Rule availability that determines which rules are available, blocked, final,
withdrawn, or not available.

For more information, see Setting rule status and availability.

• In some cases, the value of a circumstance property.

For more information about circumstancing rules, see Creating a rule specialized
by circumstance.

The output of the resolution process is the first rule that matches all the criteria. In
some scenarios, the system fails to find a rule and the process stops. Then, the system
can start an exception flow, for example for a case type, or return a message about a
failure.

©2023 Pegasystems Inc

 Pega Platform 8.8 108

Rule resolution process

The following list describes the consecutive steps that the system performs in the rule
resolution process:

1. The system checks the rules cache.

By using rules that are already in the rules cache, the system avoids additional
database lookups.

For more information about the rules cache, see the How the rules cache is
populated module on Pega Academy.

If the system finds the rule in the cache, the rule resolution process moves to step
8.

2. The system chooses instances with the correct purpose and puts them in a
temporary list.

The purpose combines all the key parts of a rule.

For example, for an activity rule, the key parts include:

• The Applies to class that defines the activity.
• The activity name.
In another example, for a field value, the key parts include:
• The Applies to class, as above.
• The field name, such as pyActionPrompt.
• The field value, such as ViewHistory.
3. The system discards all unavailable rules and removes them from the temporary
list.
4. The system discards inapplicable rulesets and versions.

The system removes from the list rules that belong to rulesets and versions that
are not available for the current requestor, which can be a user who is currently
logged in, a REST API call, or any factor that triggers rule processing. For example,

©2023 Pegasystems Inc

 Pega Platform 8.8 109

if the current user can access the SampleRuleset:05-01-01 ruleset version, the
system removes rules that belong to SampleRuleset:04 or SampleRuleset:06.

5. The system discards all candidates that are outside of class inheritance of the
current class.

In the temporary list for rule resolution, the system only maintains rules in classes
from which the current class descends either by pattern or direct inheritance. For
more information about class inheritance, see Understanding class hierarchy and
inheritance.

Note: This step is not applicable to rules that do not have the Use class-
based inheritance to arrive at the correct rule to execute check box
selected in their class definition.

6. The system ranks the remaining rules in the list by analyzing the following aspects,
in the following order:
a. Class
b. Ruleset

Note: Default rules that you save to a branch or privately check out
are in their own ruleset.

c. Circumstance
d. Circumstance date
e. Version
7. The system adds the rules that remain in the list to the cache as selectable for
use.
8. The system finds the best rule instance and checks for duplicates.
The process searches down the list for the first rule that matches the following
criteria:

©2023 Pegasystems Inc

 Pega Platform 8.8 110

• The rule exactly matches a circumstanced rule.

• The rule has the correct circumstanced date.
• The rule is in the correct date/time range.

When the system finds a rule that matches these conditions, the process checks
whether the next rule in the list is equally correct. If the next rule is correct, the
process sends a message about duplicate rules in the system and stops
processing. If the rule resolution process finds no duplicates, the system prepares
to use the rule that matches the listed conditions.

9. The system checks whether rule availability is not Blocked. If the rule is blocked,
the system sends a message that it cannot find an appropriate rule to use.
10. The system verifies that the requestor is authorized to view the rule. If the
requestor can view the rule, the system uses the rule as the output of the rule
resolution process. If not, the system sends a message that it cannot find an
appropriate rule to use.

The following figure shows a diagram that describes consecutive actions that the
system performs during rule resolution. In the figure the rule resolution process is
successful and the system applies a selected rule at run time:

©2023 Pegasystems Inc

 Pega Platform 8.8 111

Rule resolution process

For example:

Your use of an application can cause Pega Platform to search for a flow named
Repair in the Work-Contract-Application-Complete class. The system first examines
rules in the Work-Contract-Application-Complete class, and then, if no match is
available, searches higher classes in the class hierarchy. Only flows that belong to
rulesets and versions that are present in your ruleset list are candidates.

©2023 Pegasystems Inc

 Pega Platform 8.8 112

The following figure shows a schema of a rule resolution process that searches
through the Work-Contract-Application-Complete class, and then moves to classes
that are higher in a class hierarchy to find the appropriate rule:

Rule resolution process in a class hierarchy

©2023 Pegasystems Inc

 Pega Platform 8.8 113

Rule resolution exceptions

Some rule types have instances that are not associated with a ruleset and version, and
no rule resolution occurs when processing requires an instance of these rules.
Additionally, some rule types do not support circumstanced processing.

Rule resolution in branches and withdrawn rules

When you work in branches, each branch has its own rulesets that the system uses for
rule resolution. However, withdrawn rules are an exception to this general behavior.

Rules marked as withdrawn in branch rulesets, such as deleted UI views, are not
withdrawn from the main ruleset during development. They are withdrawn in the
branch ruleset. Because the system skips over withdrawn rules when in different
rulesets, the withdrawn (deleted) rule can still be resolved in the main ruleset. When
you move the changed rule to the origin ruleset by merging the branch, the system
honors the withdrawn rule and does not resolve it.

For example:

Rule A is available in TestRS:01-01-01, but the same rule A is withdrawn in

TestRS:01-01-02. Rule resolution returns an empty result when you call rule A.

In the next example, rule resolution logic might return some rules even though they are
withdrawn in a branch because the rules are available in the origin ruleset.

For example:

Rule A is available in TestRS:01-01-01. You withdraw rule A and check it into a

branch named TestingBR. The withdrawn Rule A is now in the automatically
generated ruleset TestRS_Branch_TestingBR:01-01-01. The branch ruleset is at the
top of the stack, but when rule resolution returns rule A, the system returns rule
A from TestRS:01-01-01.

©2023 Pegasystems Inc

 Pega Platform 8.8 114

• Ruleset list layers

• Ruleset list usage during rule resolution

• Viewing your application ruleset list

• Using pattern inheritance for rule resolution

• Creating a rule specialized by circumstance

• Organizing rules into rulesets
• Organizing rules into classes
• Understanding class hierarchy and inheritance
• Creating rules

Ruleset list layers

A completed ruleset list contains sublists of ruleset versions, arranged in two layers.
The following table presents the order of the ruleset list.

Note: Order is significant at the layer, sublist level, and within each sublist.

Layer Ruleset types Notes

1 Personal This ruleset, at the top of

the ruleset list, holds rules
checked out by the
operator. Such rules are not
visible to any requestor
except those of operators
who have the Allow Rule
Checkout? check box
selected on the Security tab
of the Operator ID instance.

©2023 Pegasystems Inc

 Pega Platform 8.8 115

Layer Ruleset types Notes

The name of the ruleset

matches the Operator ID.

This single ruleset has no

version and is included
implicitly when the system
assembles the ruleset list at
log-on. You do not need to
reference the personal
ruleset on the Access Group
form or any other form.

2 Localized If the application has been

localized, rulesets with
names ending in a locale
suffix (such as _it_IT for
Italian as spoken in Italy, or
_fr_CA for French Canadian)
display here.

Typically, these rulesets

contain only field values. If
the application has not been
localized, this layer is empty.

3 Mobilized If the application has been

extended to support mobile
devices, rulesets with names
ending in the suffix _mobile
display in this layer. These
rulesets contain portals,
sections, flow actions,

©2023 Pegasystems Inc

 Pega Platform 8.8 116

Layer Ruleset types Notes

navigation rules, and

controls that are selected by
rule resolution when the
HTTP User-Agent value
indicates that an HTTP
request is from a mobile
device.

If the application has not

been mobilized, this layer is
empty.

4 Production Ruleset versions (if any)

listed in the Production
Rulesets array on the Layout
tab of the Access Group
form.

5 Application (current) Ruleset versions listed in the

Application rulesets array
on the General tab of the
Application rule form for the
current application. A
branch ruleset (if any)
displays immediately above
the ruleset from which it
branched.

Any shared or component

ruleset versions listed in the
Component and shared
rulesets array on the

©2023 Pegasystems Inc

 Pega Platform 8.8 117

Layer Ruleset types Notes

General tab of the

Application rule form for the
current application, in the
order they display on the
tab.

The system assembles

layers 5 and 6 from ruleset
versions listed in the
Application rulesets area of
the General tab of any
Application rule that it
encounters during log-on
when it processes the data
instances that contribute to
the rulesets list at login.

6 (multiple) Application (built-on) Ruleset versions for built-on

applications referenced in
the current application rule.
If an application references
a lower built-on application,
there is a layer for each
application in the same
relationship as the
application rules, and the
contents of the Component
and shared rulesets area of
application rules referenced
through the Built on

©2023 Pegasystems Inc

 Pega Platform 8.8 118

Layer Ruleset types Notes

application(s) field are

ignored.

7 PegaRULES Rulesets and versions as

listed in the PegaRULES (or
PegaDM) application rule
that the application is
ultimately built on,
excluding the Pega-RULES
ruleset version.

8 Pega-RULES:NN-NN A version of the foundation

rulesets.

• Internationalization and localization

Ruleset list usage during rule resolution

Each requestor's use of the system continually causes the system to search for a rule
instance, which is known as rule resolution. This search uses properties from many
sources to find the most appropriate rule for the current need, including class
inheritance, security and access control restrictions, and the ruleset list.

During rule resolution, the system uses the ruleset list as it:

• Searches the rules in the PegaRULES database repeatedly, first using the topmost
application on the list, then the next, and so on. The Pega-RULES application is
searched last.
• Ignores any rule instances that are contained in a ruleset on the list but in
versions higher than the version specified in the list.
• Treats any partial version number (such as 02-) as a wildcard or mask. For
example, matching any rule instances containing a version that starts with 02-.

Many other factors influence this process, such as:

©2023 Pegasystems Inc

 Pega Platform 8.8 119

• Unavailable, final, or blocked rules

• Time-based rules
• Circumstances
• Access control (whether the user has authorization to access the rule)

Viewing your application ruleset list

An application ruleset is a collection of rules that identify the components of an
application. You can view a list of your application rulesets in Dev Studio.

1. Click the Operator menu (your name), and select Profile. Your operator profile
opens.
2. Locate the Application Ruleset section to view your application ruleset list.

Result:

Your application ruleset list might include rules that you do not consider part of
the application, or might exclude rules that you expect. Consider the following
criteria:

• The application ruleset does not include your personal ruleset, which
contains the rules checked out to you.
• The application ruleset does not include rules in rulesets specified in the
Production Rulesets array in your access group.
• Rules from ruleset versions listed in the Requestor Type data instance,
Organization data instance, or Division data instance are not included,
unless these rulesets are also in the application rule.

Using pattern inheritance for rule resolution

Rule resolution always first looks for a rule that it needs in the class initially provided.

When the Find by name first (Pattern) check box (which corresponds to the Rule-Obj-
Class.pyPatternInheritance property) is selected on the Class rule form, the system uses

©2023 Pegasystems Inc

 Pega Platform 8.8 120

pattern inheritance for a class. Pattern inheritance causes the system to next search for
a rule in classes derived from the current class name by truncating, from the right,
alphanumeric segments that follow a hyphen.

For example, a request for a rule in the WalCare-Financial-Credit class causes the
system to search through these classes, in the order indicated:

• WalCare-Financial-Credit
• WalCare-Financial-
• WalCare-Financial
• WalCare-
• WalCare

If this check box is selected and the rule is not found, rule resolution forms a sequence
of candidate classes to search by truncating, from the left, portions of the class name
that consist only of a hyphen, or consist only of characters other than a hyphen. If no
class exists for one of these computed names, rule resolution continues with the next
prefix.

The algorithm

For a class using pattern inheritance, the following is a simplified description of the rule
resolution algorithm:

1. Search each class formed by repeatedly truncating the original class name,
stopping if the needed rule is found.
2. If the pattern search finishes without finding a rule, go back to the original class
and use directed inheritance to find the parent of the original class.
3. If the parent class identified in step 2 was searched during step 1, skip it and skip
to step 5.
4. If the parent class was not previously searched, search it. Stop if the needed rule is
found.
5. If not found, determine whether the parent class uses pattern inheritance. If so,
repeat this algorithm, starting at step 1, with the parent class.

©2023 Pegasystems Inc

 Pega Platform 8.8 121

6. Otherwise, identify the parent of the parent. Continue at step 4.

The ultimate base class @baseclass is searched last.

Example

For example, assume your application requests a rule from WalCare-Financial-Credit,

which derives from PegaCare-Financial-Credit, and WalCare-Financial-Credit uses pattern
inheritance.

The system searches for the rule as follows:

1. Is the rule in WalCare-Financial-Credit? If not,

2. Is the rule in WalCare-Financial- ? If not,
3. Is the rule in WalCare-Financial ? If not,
4. Is the rule in WalCare- ? If not,
5. Is the rule in WalCare ? This is the end of the pattern. If the system still cannot find
the rule, it returns to Walcare-Financial-Credit and looks at the parent. If the
parent was previously checked because of a similar pattern, it continues with the
parent's parent.
6. Is the rule in PegaCare-Financial-Credit? If not, see if PegaCare-Financial-Credit
uses pattern inheritance first. If so, start the sequence again. If not, go next to the
parent of PegaCare-Financial-Credit.

Defining and changing the scope of rules

Adjust your application to your specific business needs by changing scope of rules. For
example, you can move a rule to another ruleset or class, so that you can reuse the rule
in a different part of your application.

• Moving rules

• Setting rule status and availability

• Creating a rule specialized by circumstance

©2023 Pegasystems Inc

 Pega Platform 8.8 122

• Creating a rule specialized by a class or ruleset

• Defining the input parameters of a rule

• Defining the pages and classes of a rule

• Rule skimming for higher ruleset versions

• Adding a custom field

Moving rules
When a rule is moved, all of the old instances are automatically removed from the
system, including their references and indexes.

Before you begin:

• The ruleset version or versions containing the rules to be copied are not to
be secured.

• The class must allow rules in the target ruleset.

• Rules must have an Applies To key part matching the single source class to
be moved.

• Rules must be checked in to be moved.

• The moved rule does note have the same class, other keys, and ruleset
version as an existing rule.

1. In the Application Explorer, right-click the class that contains the rules you want to
move.
2. In the context menu, select Refactor > Move rules and specify the following filters
to define where to move the rules.

©2023 Pegasystems Inc

 Pega Platform 8.8 123

• Class - Select the destination class to contain the moved rules.

• Ruleset - Select the ruleset to contain the rules after they are moved. This
can be the ruleset that currently contains the rule, or a different ruleset.

• Version - Select the ruleset version to contain the rules after they are moved.
This can be the version that currently contains the rule or a different version.

3. In the Rule Type column, select one or more check boxes to indicate which rule
types to move from the list of applicable rule types that can be moved.
4. Click Move.

Result:

When the process is complete, the form displays the results of the tool. Rules
that are not moved are marked with a red X. Hold the mouse over the red X for
information about why the rule did not move.

Setting rule status and availability

Set rule status and availability to elaborate on the usage information that you provide,
and ensure that users interact with the correct version of your rule at run time. By
setting rule status and availability, you also define application behavior during rule
resolution, and how users can interact with rules at design time. As a result, you ensure
that your application works correctly even if users apply extensions and make
modifications.For example, if you need a core functionality of your application to
remain unchanged, you can set the status of rules that build the functionality as final,
because users cannot override final rules.

1. In the navigation pane of Dev Studio, click Records.

2. Expand the category that stores your rule, and then select a subcategory.

©2023 Pegasystems Inc

 Pega Platform 8.8 124

For example:

Click Process > Service Level Agreement.

3. In the header of the form, next to the short description, click the rule availability
label.
Pega Platform displays rule availability in brackets.
4. In the Availability list, select an option to control how your application selects the
rule during rule resolution:
You cannot change the availability of some rule types, such as classes and
rulesets, which are always available to users.
• To consider the rule in rule resolution, select Available.
• To exclude the rule from rule resolution and disable validation logic so that
you can continue to edit the rule even if errors occur, select Not available.
• To consider the rule during rule resolution but to stop processing and return
an error to the user when the user selects the rule, select Blocked.
• To consider the rule during rule resolution but prevent users from extending
the rule by copying it to a different ruleset unless the ruleset is a higher
version of the current ruleset, select Final.
• To exclude the rule and all instances with the same name in previous
versions of the same major-version ruleset, from rule resolution, select
Withdrawn.
5. In the Status list, select an option to indicate how users interact with the rule:
• To enable users to provide standard input parameters to this rule and
receive standard return values or results, select API.
• To communicate that Pega Platform no longer supports the rule, select
Deprecated.
• To enable users to override the rule to provide custom functionality, select
Extension.
• To enable users to select this rule as a starting point to save time when they
create a rule, select Template.
6. Click OK.

©2023 Pegasystems Inc

 Pega Platform 8.8 125

7. Click Save.

• Troubleshooting final rules

• Troubleshooting blocked rules

• Extension points

• Base rules
• Rule resolution

Troubleshooting final rules

After a rule is marked as final, no one can create a second rule with the same visible key
in any ruleset other than the ruleset that the first rule belongs to. If the ruleset version
of a final rule is locked, you cannot create a second rule with the same visible key in any
version of any ruleset, except a higher version of the ruleset containing the final rule.

You cannot override a final rule except through a higher version in the same ruleset.
Many rules in the Pega-* rulesets are marked Final because correct operation of these
rules is essential to ensure the integrity and security of your system. However, most
standard rules have the Availability field set to Available rather than Final; you can
override those rules in your application.

Note: You cannot use circumstances or time-qualified rules to override a final

rule.

Note: You can override a final rule with a sibling rule in a language-specific
ruleset.

©2023 Pegasystems Inc

 Pega Platform 8.8 126

Conflicts

A final rule conflict arises if a rule is marked final but rules with that same name also
exist in other rulesets. This rare situation can arise when rulesets are uploaded with the
Import landing page tab or through other unusual means.

You can find final rules that have both the same name and other visible key parts by
using the Final Conflicts report Rule-.ListThisRuleFinalCollisions.ALL. Eliminate any
conflicts by deleting one of each conflicting pair until this report is empty. To access this
report, select Dev Studio > Application > Inventory > Inventory Reports . Select Rule as
the Category and enter "final" as the Search Text.

• Setting rule status and availability

• Extension points
• Creating rules
• Copying a rule or data instance

Troubleshooting blocked rules

Rule resolution processing is halted (with no rule found) when it encounters blocked
rules. The rule form colors change from greens to grays for blocked rules.

Blocked and blocked-by-another

A rule instance is blocked-by-another if its Availability value is set to Available but a

higher-numbered version of this rule (same name or key, same ruleset) has the
Availability set to Blocked.

Available rules with that name or key and a different ruleset may be blocked-by-another
as well, if their ruleset version is appears beneath the ruleset version of the Blocked
rule on the user's ruleset list.

When rule resolution selects a rule that is blocked, that rule and all others (same name
or key, any ruleset) are not executable.

©2023 Pegasystems Inc

 Pega Platform 8.8 127

To make a rule available "above" a blocked rule (that belongs to a secure ruleset
version), choose a higher version number or a ruleset that appears higher on your (and
other users') ruleset list.

Circumstances

If a rule has Availability set to Blocked but also has a non-blank Circumstance Property,
the blocking affect applies both to that rule and the base or underlying rule that has no
Circumstance property. A rule resolution search that meets the Circumstance Property
value stops (with no rule found). The Availability setting in the underlying rule is not
relevant.

However, the converse does not hold. If the rule with a Circumstance Property has
Availability set to Available, and the base rule has Availability set to Blocked, a rule
request matching the circumstance property and value is successful at finding and
using the circumstance-qualified rule.

Blocked rules included in ZIP archives

When you create a ZIP archive containing a ruleset version, any blocked rules
associated with that ruleset Version are included in the archive (and remain blocked
when uploaded into on a destination system).

On a destination system, a blocked rule can in some cases block a different set of other
rules than it blocked on the source system.

Blocked rules and skimming

When skimming to a new minor or major ruleset Version, Blocked rules are always
copied since their purpose is to block all similar rules regardless of ruleset name.
Blocked rules can be used, for example, to block another rule which belongs to a
ruleset name in an underlying Application layer that will be untouched by the skim
process.

• Setting rule status and availability

©2023 Pegasystems Inc

 Pega Platform 8.8 128

• Creating rules
• Copying a rule or data instance

Extension points
An extension point is an activity or other rule that is designed and intended to be
overridden to meet application needs. Many such rules are empty stubs that contain no
steps. Typically, the overriding rule is in a derived class.

The Pega Platform itself includes a few dozen extension points. For example, the empty
activity Code-Security.ApplicationProfileSetup is executed when an operator logs on. If
your application requires special initialization processing for authenticated operators,
you can override this application (in your application's ruleset) to perform such
processing.

Extension points in frameworks

An extension point is a rule (typically a blank or empty rule) that is marked as an

Extension in the Status field on the New or Save As dialog box. The corresponding
property Rule-.pyMethodStatus does not appear on the rule form, does not affect rule
resolution or execution of the rule, and cannot be changed.

For example, a flow in a framework may include an Integrator shape that connects to a
customer master file database. In the framework ruleset, this can be an empty activity
with an activity type of Connect, marked as an extension. When rulesets are an
implementation of that framework, the developers must override the empty activity
with a functioning interface to their customer master file.

• Setting rule status and availability

Creating a rule specialized by circumstance

Create a rule specialized by circumstance to provide a variant of the rule that your
application triggers only conditionally under specified conditions. By creating
specialized or circumstance rules, you address dynamic business requirements without

©2023 Pegasystems Inc

 Pega Platform 8.8 129

changing the core logic of your application.For example, in an application to review loan
requests, additional processing can start only when the request amount exceeds a
value that you specify. You can also specify a time frame when the rule is active and
available for rule resolution. When you circumstance rules instead of applying other
solutions, such as decision tables, you create an application that is easier to maintain
and edit if you need any adjustments in the future.

Before you begin:

If you want to circumstance a rule by using a set of conditions, create a

circumstance template and definition. For more information, see Creating a
circumstance template and Creating a circumstance definition.

For relevant training materials, see a Circumstancing case processing module on Pega
Academy.

1. In the navigation pane of Dev Studio, click Records.

2. Expand the category that you want to open, and then open the subcategory that
holds the rule that you want to circumstance.

For example:

Expand Process, and then click Flow.

3. In the list of instances, click the rule that you want to open.
4. In the rule form header, open the new rule form:
• If the rule is checked out, click the Down arrow next to the Save button, and
then click Specialize by circumstance.
• If the rule is checked in, click the Down arrow next to the Save as button, and
then click Specialize by circumstance.
5. Optional: To provide information about the purpose of the new rule, in the Label
field, enter a new short description.
The identifier remains the same, even if you provide a new label.
6. Define circumstance conditions:

©2023 Pegasystems Inc

 Pega Platform 8.8 130

Choices Actions

Circumstance the rule by a set of a. In the CIRCUMSTANCE BY section,

conditions select Template.
b. In the Template field, enter the
template that stores properties to
evaluate.
c. In the Definition field, enter a
definition that references properties
from the template.
At run time, your application
resolves the rule if conditions from
the definition evaluate to true.

Circumstance the rule by property a. In the CIRCUMSTANCE BY section,

select Property and Date.
b. In the Property field, enter a
property to evaluate at run time.

For example:

Enter LoanAmount.

c. In the Value field, enter a value to

evaluate against the property.

For example:

Enter 5000.

Circumstance the rule by date a. In the CIRCUMSTANCE BY section,

select Property and Date.
b. In the Date property field, enter a
property that stores a date to
evaluate at run time.

©2023 Pegasystems Inc

 Pega Platform 8.8 131

Choices Actions

c. Optional: To specify an exact

starting time when an application
can resolve the rule, in the Start
Date field, select the date.
d. Optional: To specify an exact time
after which an application omits the
rule in rule resolution, in the End
Date field, select the date.

If you leave a date property blank,

your application evaluates the
specified time period against the
current system date.

If the rule is active during the

specified time interval only, then at
all other times, the base rule is
active. During rule resolution, if two
or more date circumstance versions
are candidates at the current time
and date, the application selects the
candidates with the nearest end
date. If multiple remaining
candidate rules have the same end
date, the application picks the
candidate with the most recent start
date. For more information about
possible date combinations and the
business-logic requirements that
they meet, see Date combinations
and business requirements.

©2023 Pegasystems Inc

 Pega Platform 8.8 132

Tip: In specific business scenarios, you can also circumstance rules by a

combination of property and date.

7. Optional: To override the default work item that your application associates with
this development change, press the Down arrow key in the Work item to associate
field, and then select a work item.
For more information about your default work item, see Setting your current work
item.
8. Update the values in the Context and Add to ruleset lists as appropriate.
9. Click Create and open.

Result:

At run time, an application resolves the rule when the conditions that you
specified evaluate to true. If the conditions evaluate to false, the application
resolves the base form of the rule.

• Creating a circumstance template

• Creating a circumstance definition

• Controlling the order of circumstance definitions

• Redirected rule

• Base rules

• Finding rules by circumstance

• Specializing a case type

• Rule resolution exceptions

• Setting rule status and availability

©2023 Pegasystems Inc

 Pega Platform 8.8 133

• Creating rules
• Circumstance rule examples

Creating a circumstance template

Create a circumstance template to define a set of conditions that your application
evaluates at run time to determine whether a rule is available for rule resolution. By
creating circumstance templates, you deliver a flexible application that starts relevant
processing under specified conditions, without implementing complex and advanced
business-logic solutions.For example, in an application to review loan requests, you can
define a circumstance template with properties that hold a loan amount, a customer
income, and an account type that the customer has. At run time, the application starts
relevant processing when the values of the properties meet specified conditions.

Creating a circumstance template is a first step in circumstancing a rule. As the

template holds only properties, you also need conditions to evaluate against the values
of the properties.

1. In the header of Dev Studio, click Create > Technical > Circumstance Template.
2. On the Circumstance Template Record Configuration form, enter values in the
fields to define the context of the template:
a. In the Label field, enter text that describes the purpose of the circumstance
template.
b. Optional: To change the default identifier for the circumstance template,
click Edit, and then provide a unique value in the Identifier field.
c. In the Context section, select the application to store the template.
d. In the Apply to field, press the Down arrow key and select the class that
defines the scope of the circumstance template.
e. In the Add to ruleset field, select the name and version of a ruleset that
stores the circumstance template.
f. Optional: To override the default work item that your application associates
with this development change, in the Work item to associate field, press the
Down arrow key, and then select a work item.

©2023 Pegasystems Inc

 Pega Platform 8.8 134

For more information about your default work item, see Setting your current
work item.
3. Click Create and open.
4. On the Template tab, in the Property field, press the Down arrow key, and then
select the name of a property that you want to evaluate at run time.

For example:

Select LoanAmount.

5. In the Label field, enter the name that corresponds with the property in a
circumstance definition.
When you create a circumstance definition, which has a table layout, each row
header displays a property label.
6. Optional: To add more properties, click Add a row, and then repeat steps 4
through 5.
7. Click Save.

What to do next:

Create a circumstance definition that stores conditions to evaluate against the

circumstance template. For more information, see Creating a circumstance
definition.

Related concepts

• Building logic and calculating values in your application

Related tasks

• Defining and changing the scope of rules

• Setting rule status and availability
• Creating rules

©2023 Pegasystems Inc

 Pega Platform 8.8 135

Creating a circumstance definition

Begin relevant processing in your application only under specified conditions by
creating a circumstance definition. When you implement circumstancing in your
application, you provide flexible solutions without defining complex logic. As a result,
you increase efficiency and design an application that is easier to maintain in the future
if your business requirements change.For example, in a banking application, if your
circumstance template includes a LoanAmount property, and the definition includes the
value 5000 with an operator >, the application resolves the circumstance rule only
when the loan request amount is greater than 5000.

Before you begin:

Create a circumstance template that stores properties to evaluate by the

circumstance definition. For more information, see Creating a circumstance
template.

1. In the header of Dev Studio, click Create > Technical > Circumstance Definition.
2. On the Create Circumstance Definition form, enter values in the fields to define
the context of the definition:
a. In the Label field, enter text that describes the purpose of the circumstance
definition.
b. Optional: To change the default identifier for the circumstance definition,
click Edit, and then in the Identifier field, provide a unique value.
c. In the Template Name field, press the Down arrow key, and then select the
circumstance template that your circumstance definition implements.
d. In the Context section, select the application to store the template.
e. In the Apply to field, press the Down arrow key and select the class that
defines the scope of the circumstance definition.
f. In the Add to ruleset field, select the name and version of a ruleset that
stores the circumstance definition.

©2023 Pegasystems Inc

 Pega Platform 8.8 136

g. Optional: To override the default work item that your application associates
with this development change, in the Work item to associate field, press the
Down arrow key, and then select a work item.
For more information about your default work item, see Setting your current
work item.
3. Click Create and open.
4. On the Definition tab, click the column header to choose which operations the
column supports:
• For columns that evaluate properties from the template against a single
value, select an operator from the Use Operator list, for example >.
• For columns that evaluate properties from the template against a range of
values, select the Use Range check box, and then choose operators from the
Starting Range and End Range lists, for example >= and <=.
5. Click Save.
6. Click a cell in a table that you want to define, and then enter a value or an
expression that evaluates properties in the template.

For example:

To evaluate loan amounts greater than 5000, use a single operator >, and
then enter 5000.

7. Optional: To provide more values for evaluation, add rows to the table:
• To add a row before the current cell, on the toolbar, click Insert Row Before,
and then repeat step 6.
• To add a row after the current cell, on the toolbar, click Insert Row After, and
then repeat step 6.

Tip: As your application evaluates the table from top to bottom, to save
time and resources, place the most likely outcomes at the top of the
table.

©2023 Pegasystems Inc

 Pega Platform 8.8 137

8. Optional: To ensure that your application can process the table, check the table
for conflicts by clicking Show conflicts on the toolbar.

Result:

A warning icon appears in rows that are unreachable or empty.

9. Click Save.

Result:

At run time, an application evaluates the values from the circumstance definition
against the properties in the circumstance template and resolves the rule only
when the values evaluate to true.

• Date circumstance rule

• Circumstance rule examples

• Circumstance definitions

• Date combinations and business requirements

Related concepts

• Building logic and calculating values in your application

Related tasks

• Defining and changing the scope of rules

• Setting rule status and availability
• Creating rules

©2023 Pegasystems Inc

 Pega Platform 8.8 138

Date circumstance rule

A date circumstance rule is a circumstance that is only resolved during a specified range
of time.

When a date circumstance is applied, the value of the date property and the specified
start and end date determine the time period during which the rule will be active.

Restrictions

• Date circumstances can only be created for supported rule types. This is
controlled by the Allow rules that are valid only for a certain period of time check
box on the Class form.
• You cannot override a final rule with a date circumstance rule.
• When date circumstance rules are used in a multinode system, be sure to
synchronize the internal clocks of all the server nodes in the cluster. Clock
differences of less than a few seconds may lead to incorrect application results.
Most operating systems offer facilities for such synchronization.

• Setting rule status and availability

• Creating a rule specialized by circumstance
• Circumstance rule examples

Using more than one time-qualified rule

Your application can include multiple date range circumstances for the same base rule
with overlapping (but not identical) date and time intervals. At run-time, rule resolution
processing finds all the time-qualified rules with an interval that includes the current
date and time. It then selects the best rule to run based on the following tests:

1. Examine the end dates on each candidate time-qualified rule. Choose the rule or
rules that have the nearest end date, discarding others.
2. If only one candidate remains, that rule is the result of this phase of rule
resolution processing.

©2023 Pegasystems Inc

 Pega Platform 8.8 139

3. If two or more candidates remain, the one with the most recent start date is
selected.

• Date circumstance rule

Contrasting time-qualified rules and historical processing

Pega Platform offers two separate features that can cause processing to be dependent
on a date or time value. Which of these to apply to best meet an application need
depends on the nature of the rules affected and the requirements and environment of
the application:

• Date circumstance rules

• Historical processing capability

How circumstance rules evaluate time

Date circumstance rules are specialized versions of a base rule that only execute when
certain time conditions are met.

Based on the combination of specified date property and the time interval, a rule can
be resolved in one of the following ways:

Result Date Start Date End Date

property

Rule to be effective only if the value of Select Select Select

the specified date property occurs within
a date range

Rule to be effective only if the value of Select Select

the specified date property occurs after
a certain date

Rule to be effective only within a date Select Select

range

©2023 Pegasystems Inc

 Pega Platform 8.8 140

Result Date Start Date End Date

property

Rule to be effective only after a certain Select

date

How historical processing evaluates time

The historical processing capability applies to an entire ruleset version, not to a rule.
This capability is unrelated to the concept of circumstancing and base rules.

With careful advanced design, this feature allows an application (for the current
requestor) to operate according to rules as they were on a specific past date. Such
processing is useful to reconstruct past behavior or apply past policies.

• Creating a rule specialized by circumstance

Circumstance rule examples

Assume that you have different pricing levels for your customers. You first define a
base pricing rule for all customers. Then you qualify the base rule by creating
circumstanced rules for customers at different buying levels. The
property .CustomerType is part of the customer order and has values of "Silver" and
"Gold". In this example, a customer has purchased a $100 item. Using the property and
values, you create circumstanced instances of the base rules as shown here:

• Base — if .CustomerType="none", then Price =$100

• Circumstance 1 — if .CustomerType = “Gold”, then price = $100 - 25%
• Circumstance 2 — if .CustomerType =“Silver”, then price = $100 - 10%

When the system processes the order, the value of that property dictates which rule is
run and thereby determines the discount (if any) the customer receives.

©2023 Pegasystems Inc

 Pega Platform 8.8 141

Properties in a circumstance

The example above used the single value property.CustomerType to qualify the base
pricing rule. Specifying a property value in a circumstance is only supported by certain
rule types; refer to the Allow Selection based on Property Rules? check box selected on
the Class form defining the rule type.

You can also specify a date property along with the time period against which the value
of the date property is evaluated.

For example, an annuity is an investment vehicle providing scheduled payments for

many years (or in some cases for the life of the investor). A work item supporting
annuity processing needs that an expiration date (say ExpireDate), occurs between
December 15, 2015 and December 31, 2015. If a few processing aspects of the work
item depend on this value, they can be derived from a base rule by specifying a Date
property of .ExpireDate and the start date and end date as 12/31/2015 and 12/31/2015.

A single rule can contain both a circumstance property and a date circumstance
property. For the circumstance property value, an exact match is required. For the date
circumstance, when a date property is specified its value must occur after the specified
start date and before the end date. If a date property is not specified, the system time
at the time of processing should occur after the specified start date and before the end
date.

Note: If two base rules with the same Apply to key part and family name both
have one or more associated property circumstanced rules, the same
circumstance property must be used. For example, if activity MyClass.Alpha
has an associated circumstanced rule using property .State, then another
activity MyClass.Alpha cannot have a circumstance rule with any property
other than .State.

©2023 Pegasystems Inc

 Pega Platform 8.8 142

Dates in a circumstance

A date circumstance defines a period of time where a version is eligible for selection
during rule resolution.

For example, assume that the normal service-level agreement for a retail operation
allows four days as the goal time. Management might decide (to accommodate an
extraordinary volume crunch in December or January) to create a temporary rule with
six days as the goal time. The Start Date of the circumstanced by date rule can be set to
December 1 of a year, and the End Date to January 31. No other changes to the
application are necessary; assignments created anytime during those two months have
the longer intervals.

Multiple properties in a circumstance>

You can use multiple properties to circumstance a rule by more than one feature. For
example, an insurance company may be required to collect, for every state, claims that
exceed a specific amount and the method by which the claims were conveyed (letter,
phone, email, and so on). Another example may be the need for a rule that is
specialized by an age range and not an absolute value.

If you use multiple properties in a circumstance, you select the following records:

• Circumstance Templates (Rule-Circumstance-Template rule type)

• Circumstance Definitions (Rule-Circumstance-Definition rule type)

Note:

• For decision tables, you can redirect one circumstanced rule to another
circumstanced rule (a peer with the same base rule), to reduce the
number of distinct rules that you need to maintain. Select the Redirect
this rule check box on the Results tab.
• A rule cannot be a circumstance if another rule of the same type and
name exists in a different class, even if the classes are unrelated and

©2023 Pegasystems Inc

 Pega Platform 8.8 143

have no inheritance relationship, even if the conflicting rules are set to

withdrawn rule. This is because the Apples To class of a rule is not taken
into account when looking for conflicting circumstance rule instances,
only the name.

• Creating a rule specialized by circumstance

• Finding rules by circumstance
• Rule resolution
• Circumstance definitions

Circumstance definitions
A circumstance is an optional qualification available for supported rule types and is
built upon the base rule.

Using circumstances in your application allows you to easily support a variety of use
cases. For example, you might want a different data transform to execute depending on
a customer's geographic location (for example, when .StateCode = "MA"). Instead of
maintaining the logic for all cases in one large rule, start with a base rule and extend (or
specialize) it as needed. At runtime, the Pega Platform automatically selects the correct
version to execute as part of its rule resolution process.

The following figure illustrates example logic for evaluating geographic location and
other properties in a case.

You can create a circumstance of a base rule by a single value property, template
(multiple properties), or date.

©2023 Pegasystems Inc

 Pega Platform 8.8 144

Note: If you have upgraded to Pega 7.2, all date circumstance rules will be
upgraded automatically and can be modified, except the rules circumstanced
by date range and as-of date. These rules continue to run without issues but
must be manually upgraded to use the new date circumstancing options.

• Creating a circumstance definition

Date combinations and business requirements

The following table lists the possible date combinations and the business-logic
requirements they meet when you circumstance by date.

Business requirement Specify date Specify Specify end

property start date date

Rule to be effective only if the value of Yes Yes Yes

the specified date property occurs within
a date range

Rule to be effective only if the value of Yes Yes No

the specified date property occurs after
a certain date

Rule to be effective only within a date No Yes Yes

range

Rule to be effective only after a certain No Yes No

date

• Creating a rule specialized by circumstance

Controlling the order of circumstance definitions

Provide relevant processing in scenarios when multiple conditions evaluate to true, to
ensure that users of your application interact with the intended data and application
behavior. By defining the priority of circumstance definitions, you determine how your

©2023 Pegasystems Inc

 Pega Platform 8.8 145

application behaves when more than one definition meets specified

conditions.Consider a situation in which a circumstance template includes a property
that holds a loan amount. Two circumstance definitions correspond with the template;
one definition that evaluates the property against values greater than 4,000, and a
second definition that evaluates a property against values greater than 7,000. A
customer creates a loan request for 10,000. Because both circumstance definitions
evaluate to true, you can select which definition you want your application to use.

Before you begin:

Define a circumstance template that stores properties and at least two

circumstance definitions that store values to evaluate against the template. For
more information, see Creating a circumstance template and Creating a
circumstance definition.

1. In the navigation pane of Dev Studio, click Records.

2. Expand the Technical category, and then click Circumstance Template.
3. In the list of circumstance templates instances, click the template that you want to
open.
4. Click the Definitions tab.

Result:

The All Definitions section displays all circumstance definitions that

correspond to the open circumstance template.

5. In the Priority Definitions section, in the field in row 1, enter the circumstance
definition that you want your application to run first.
6. To add more circumstance definitions, click Add a row, and then in the row that
appears, enter the definition that you want your application to run next.

Tip: You can also drag a field to a different position in the list to change
its run-time priority.

©2023 Pegasystems Inc

 Pega Platform 8.8 146

7. To check the correctness of your circumstance definitions, on the toolbar, click

Show Conflicts.

Result:

A read-only decision table opens in a separate window that displays all the
definition values for all the circumstance definition rules in the specified
order. A warning icon appears next to the rows of the table that are
unreachable. A warning message also appears when you attempt to save a
form that contains conflicts. Even though the tables might not have any
conflicts individually, conflicts might generate when the system assembles
the definitions as a single table at run time.

8. Click Save.

Related concepts

• Building logic and calculating values in your application

Related tasks

• Creating rules

Redirected rule
A redirected rule is a circumstance rule that is configured to reference another
circumstance rule for the same base rule. Redirection is available for Decision Tables
( Rule-Declare-DecisionTable).

At run time, if rule resolution initially selects a redirected rule, the system accesses the
target of the redirection, and that second rule runs. (If the target is not found, the base
rule runs.) The system ignores all fields on the redirected rule form, except for the
redirection details and the rule name.

©2023 Pegasystems Inc

 Pega Platform 8.8 147

Benefits

Redirection can simplify maintenance of a set of circumstance rules. For example, an

application might include a decision table named SalesTax that computes state sales
taxes for a state and is circumstanced by state code, such as VA for Virginia.

Your application needs one base rule and 50 circumstance-qualified rules, one for each
state code. However, if the tax structure of several states (such as Alaska, Delaware,
Florida, Montana, and New Hampshire) is identical, you can:

• Create a circumstance rule for Alaska (with AK as the circumstance value) that
defines the Alaska state sales tax.
• Create circumstance rules for Delaware, Florida, Montana, and New Hampshire
which are marked to redirect to the AK rule.

Redirection does not reduce the number of circumstance rules you need to create, but
it can reduce your maintenance effort when several of them operate alike (that is, are
functionally equivalent).

Note:

• Redirection is possible only for single value circumstancing and not for
template circumstancing.
• The target of a redirected rule can be another redirected rule.
• You cannot redirect a rule to itself. You should avoid creating a circular
set of redirections (A to B and B to A), as doing so causes an exception at
run time.

• Creating a redirected rule

• Circumstance rule examples
• Creating a rule specialized by circumstance

©2023 Pegasystems Inc

 Pega Platform 8.8 148

Creating a redirected rule

To create redirected rules, which are circumstance rules that are configured to
reference other circumstance rules for the same base rules, complete the following
tasks.

1. Create a base rule for the decision table.

2. Using the Save As toolbar operation, create each circumstanced rule that provides
distinct results.
3. Create additional circumstance rules for other values of the rule.
4. Open the circumstance rule that you want to redirect to another circumstanced
rule.
5. On the Results tab of the circumstance version of the decision table that you want
to redirect to the target rule, select the Redirect this Rule field.
6. From the Circumstance Value list, select the circumstance value of the target rule.

• Decision tables
• Creating a rule specialized by circumstance

Base rules
A base rule is the fallback rule selected by rule resolution when no other circumstance
version's criteria is met. Base rules have no circumstance qualification.

A base rule must exist for every circumstance rule.

Restrictions

• Circumstance rules are valid only when certain qualifications are met. You cannot
delete a base rule when a circumstance rule with the same key exists; the
circumstance version provides a fallback.
• For rules with an Apply to key part, the base rule can have an Apply to class that is
a parent or ancestor class of the Apply to class of the circumstance rule.

©2023 Pegasystems Inc

 Pega Platform 8.8 149

• You cannot check out a rule that is a base rule when a related circumstance rule is
checked out.
• You cannot check out the base rule of a date circumstance rule at a time between
the start and end date and time.
• If a date circumstance stream rule contains JSP tags (rather than directives), the
base rule must also contain JSP tags rather than directives. Conversely, if the date-
circumstanced rule contains directives, the base rule must contain directives.
• In releases before PRPC Version 5.2, circumstance rules with a ruleset version
number lower than the ruleset version of a base rule were ignored (never
selected) during rule resolution. Starting with PRPC Version 5.2, this is not the
default rule resolution behavior. You can copy a base rule to a higher version
without the need to also copy each of the (possibly many) circumstanced rules
associated with the base rule into that higher version. While not recommended,
you can revert to previous behavior by selecting the Base Rule check box on the
form produced by the Availability label on the rule toolbar. The Base Rule check
box only impacts rule resolution. Other tools, such as skimming a ruleset, do not
honor the check box.

• Creating a rule specialized by circumstance

• Setting rule status and availability
• Circumstance rule examples

Finding rules by circumstance

To verify if an existing rule is either a base rule or a circumstance, open it in Dev Studio
and inspect the form header. Click the Circumstanced link to see circumstance values
or an indication that the rule is a base version. The link does not appear if the existing
rule is neither a base nor a circumstanced version.

To see all available circumstances for a given base rule, navigate to the rule in the
Application Explorer. Use the expand icon next to the name of the base rule to display
each of the circumstanced instances and their values.

©2023 Pegasystems Inc

 Pega Platform 8.8 150

Select Configure > Case Management > Tools > Find Rules > Find by Circumstance to
create a report comprising single-property and multiple-property circumstance rules.
You can filter the report by searching on the following default circumstance properties:
U.S. State Codes, Channels, and Customer Level. You can also search for circumstance
rules by entering text used in key parts ( Apply to or Identifier ) in the Name Contains
field.

For more information on how to report on circumstance rules, or how to add or change
the circumstance property columns for the report, see the Pega Community article How
to find rules with a specific circumstance.

Use the Data-Circumstance-Duplicates.CircumstanceMultiples.ALL report to identify single

circumstance rules that incorrectly use two or more different properties. Such conflicts
can arise when rules are imported into a rulesetthat already contains some
circumstanced rules. To access this report, select Configure > Application > Inventory >
Inventory Reports. Enter Rule as the Category and circumstance as the search text.

• Creating a rule specialized by circumstance

• Setting rule status and availability
• Circumstance rule examples

Specializing a case type

Specialize a case type to support variations in the way that cases are processed in your
application. Each version that you create is uniquely identified by a circumstance.

Tip: Specialized versions are not automatically added to the parent case types
of your base case type. Open the Case Type form for each parent case type to
add your specialized version as a child.

1. In the navigation pane of Dev Studio, click Case types, and then click the case type
that you want to open.

©2023 Pegasystems Inc

 Pega Platform 8.8 151

2. In the navigation pane of App Studio, click Case types, and then click the case type
that you want to open.
3. On the Settings tab, click Specialization.
4. Press the Down Arrow key in the autocomplete field and select the name of a
single-value property.

Note: Case types support specialization by a single-value property. The

property that you specify is used for this version and all future,
specialized versions that you create. This means that the autocomplete
field is hidden the next time that you follow this procedure.

5. Click + Add specialization.

6. Define a property value for the circumstance by using one of the following fields:

• Text input — Enter a string value without quotes that is consistent with the
property type.

For example, enter 100 for a property that stores integer error codes.

• Drop-down list — Select a value that maps to an entry from the property's
configured table type.

For example, select XL when the property is configured as a local list of

clothing sizes.

7. Click Save.

Result:

The values that you provide are used to create a specialized version of the base
case type. To view your specialized case types in the Case Type Explorer, expand
the name of a base case type.

©2023 Pegasystems Inc

 Pega Platform 8.8 152

Rule resolution exceptions

Understanding rule resolution of circumstance rules across rulesets can help you
troubleshoot unexpected rule resolution results.

Privately edited and branched rules

When privately edited or branched rules are matched, circumstance rules do not work
because they are in a different ruleset. In the following example, line 1 is a privately
edited rule and line 2 is a branched rule. If either of the rules is matched, the
circumstance rules are ignored.

1. MyRule in myusername@ ***

2. MyRule in MyRuleset_branch_BranchName Base rule ***
3. MyRule in MyRuleset 01-01-05 Circumstance by Property: .pyLabel = Green
4. MyRule in MyRuleset 01-01-05 Circumstance by Property: .pyLabel = Yellow
5. MyRule in MyRuleset 01-01-05 Base rule
6. MyRule in MyRuleset 01-01-04
7. MyRule in MyRuleset 01-01-03 Circumstance by Property: .pyLabel = Yellow
8. MyRule in MyRuleset 01-01-02 Circumstance by Property: .pyLabel = Green
9. MyRule in MyRuleset 01-01-02 Circumstance by Property: .pyLabel = Red
10. MyRule in MyRuleset 01-01-01 Circumstance by Property: .pyLabel = Green
11. MyRule in MyRuleset 01-01-01

Circumstance rules outside of the matched ruleset

Circumstance rules are honored only if they are in the same ruleset as the matched
non-circumstance rule. For example, if you have a rule stack as shown in the following
example, and line 3 is the matched rule, only the circumstance rules for green and
yellow are honored. All rules below line 3 are discarded even though their
circumstancing matches.

©2023 Pegasystems Inc

 Pega Platform 8.8 153

1. MyRule in MyRuleset 01-01-01 Circumstance by Property: .pyLabel = Green

2. MyRule in MyRuleset 01-01-01 Circumstance by Property: .pyLabel = Yellow
3. MyRule in MyRuleset 01-01-01
4. MyRule in BusinessRules 01-01-03 Circumstance by Property: .pyLabel = Yellow
5. MyRule in BusinessRules 01-01-02 Circumstance by Property: .pyLabel = Green
6. MyRule in BusinessRules 01-01-02 Circumstance by Property: .pyLabel = Red
7. MyRule in BusinessRules 01-01-01 Circumstance by Property: .pyLabel = Green
8. MyRule in BusinessRules 01-01-01

• Rule resolution

Creating a rule specialized by a class or ruleset

Provide a version of a rule that your application triggers only during resolution of rules
that belong to a specified class or ruleset. When you define the conditions for a rule
resolution, you ensure that users interact with actions and the application behavior that
are relevant in a given scenario. You also save time and resources because you promote
reuse across your application.

Consider a scenario in which Vehicle-Insurance and Loan-Request classes in your

application are outside a class hierarchy and have no shared rulesets, but you want to
apply a service-level agreement (SLA) rule from the Loan-Request class to the Vehicle-
Insurance class. You can specialize the SLA rule so that your application can resolve it
during processing of the Vehicle-Insurance class.

Specializing rules by class or ruleset saves time and improves consistency in your
application, because when you specialize a rule, the system does not create a new rule
instance with a new identifier but only references a rule that already exists. As a result,
when you edit a rule, your changes apply in classes and rulesets that reference that
rule, and you avoid editing multiple copies of the rule.

1. In the navigation pane of Dev Studio, click Records.

©2023 Pegasystems Inc

 Pega Platform 8.8 154

2. Expand the category that you want to open, and then open the subcategory that
holds the rule that you want to circumstance.

For example:

Expand Process, and then click Flow.

3. In the list of instances, open the rule.

4. In the rule form header, click the Down arrow next to the Save button, and then
click Specialize by class or ruleset.
5. Optional: To provide more information about the purpose of a new rule, in the
Label field, enter a new short description.
The identifier remains the same even if you provide a new label.
6. In the Context section, define a new location with which to reference your rule:
a. In the list of built-on applications, select an application layer for the rule.
b. In the Apply to field, enter a class that you want to associate with the rule.
c. In the Add to ruleset list, select a ruleset and a ruleset version to associate
with the rule.
7. Optional: To override the default work item that your application associates with
this development change, press the Down arrow key in the Work item to associate
field, and then select a work item.
For more information about your default work item, see Setting your current work
item.
8. Click Create and open.

Result:

The system resolves the rule during rule resolution of the specified class and
ruleset.

Related concepts

• Rule resolution

©2023 Pegasystems Inc

 Pega Platform 8.8 155

• Building logic and calculating values in your application

Related tasks

• Copying a rule or data instance

Defining the input parameters of a rule

Control the type of information that users can pass to a rule by defining input
parameters. By referencing these input parameters in your rule logic, you can use run-
time data to make decisions.

For example, you can define income, debt, and expense information as input
parameters to a rule in a life insurance application. At run time, the rule calculates a
debt-to-income ratio to determine which policy plan meets the customer's lifestyle.

Note: Some rules do not support parameters or support only a subset of the
following options. The names of fields vary, based on the type of rule that you
update.

1. In the navigation pane of Dev Studio, click Records.

2. Open the form for a rule that supports parameters.

For example:

To edit an activity, in the Records section, expand the Technical category,

click Activity, and then, in the list of instances, open the activity that you
want to configure.

3. Click the Parameters tab.

4. Define an input parameter that your rule supports:
a. Click the Add item icon.
b. In the Name field, enter a unique identifier.

©2023 Pegasystems Inc

 Pega Platform 8.8 156

c. In the Description field, enter text that describes how your rule logic
processes the input parameter.
d. In the Data Type list, select a format for the input parameter.
e. Optional: To require a non-null value for the input parameter, in the
Required? list, select Yes.

Note: Do not make Boolean input parameters required because

your application might interpret a false value as a null or blank
value.

f. Optional: To set the initial value of the input parameter, enter a value in the
Default Value field that corresponds to the format that you select in the
Data Type list.
5. If the input parameter has the Data Type field set to Page Name, on the Pages &
Classes tab, add a corresponding page name and class.
For more information, see Defining the pages and classes of a rule.
6. On other tabs of the rule form, update your rule logic to reference the input
parameter by using the following notation: param.[input parameter name]
7. To add another input parameter, click Add item, and then repeat steps 4 through
6.
8. Click Save.

What to do next:

You can test your changes by running the rule and providing values for the input
parameters.

• Defining the pages and classes of a rule

• Defining the local variables for an activity

©2023 Pegasystems Inc

 Pega Platform 8.8 157

Prompting users for parameter values

You can prompt users for values when they run a rule that has input parameters. By
displaying a list of options instead of a blank text box, you can help users provide
information quickly and accurately.

Note: Some rules do not support parameters or support only a subset of the
options below. Names of fields may vary, based on the type of rule that you
are updating.

1. Define the input parameters for your rule.

2. In the header of the rule form, click Actions > View references to display a list of
rules that call your rule.

3. Inspect the list to ensure that your rule runs in response to an action that a user
performs, such as a flow action, because parameter prompting does not occur
when a rule runs programmatically.

4. Click the Parameters tab.

5. In the SmartPrompt type field, enter the first key part, which is typically the class,
of the input parameter.

For example, you can enter Rule-Message to display a list of messages that are
available in the run-time class path.

6. To refine the options in the list, enter the second key part of the input parameter
in the Validate as field.

For example, you can enter pyCaption when the SmartPrompt type field is set to
Rule-Obj-FieldValue to display only field values with a field name that
contains "pyCaption".

©2023 Pegasystems Inc

 Pega Platform 8.8 158

You can also reference a property in this field.

7. Click Save.

You can test your changes by running your rule.

• Empowering knowledge workers

• Defining the input parameters of a rule

Defining the pages and classes of a rule

Many types of rules can access or update information on various clipboard pages when
they run. Most of these rule types include a Pages & Classes tab that you can use to
provide important information about what your clipboard pages will look like during
execution.

• Setting up rule prompting during when you configure forms. For example, if you
specified that a page belongs to the Work-class in the Pages & Classes tab of an
activity, when the page is used as a step page, prompting shows results from the
Work- class.
• Configuring rule validation. The information specified in the Pages and Classes tab
defines how rule references are validated during rule validation.
• Applying the default class for list elements. When you define a list or group page
on the Pages and Classes tab, the system automatically sets the class of those
elements when new entries are added.

Guidelines

To complete a Pages & Classes tab, follow these guidelines:

• Leave this tab blank if the other tabs of the rule do not reference any pages.
• Complete this tab to describe the clipboard context expected at run time.
• Page names are case-sensitive, so be sure to match the case of the page name.

©2023 Pegasystems Inc

 Pega Platform 8.8 159

• Enter the name of each page referenced explicitly on the other tabs of the rule
form. For rules that contain HTML or XML text, such as correspondence or HTML
rules , the reference can be inside a JSP tag or directive.
• To set the class of the primary page, add a row that has no value for the page
name and the desired class name.
• If you use the keyword Top on other tabs of the rule form, such as in embedded
properties, add a row with the keyword Top in the Page Name column and the
class of the top level page in the Class column. You frequently do this when the
name of the top-level page name varies in different settings.
• For an embedded page enter the full page name. You can also enter the full page
name starting with the top-level page name or with the keyword Top. For List and
Group arrays, use trailing (). For example:
◦ myPage.ListA().PageA
◦ myPage.ListA().listB()

Page names must be absolute property references. Relative references, such

as .myEmbeddedPage are not supported. Instead, use the keywords Primary
or StepPage to make the path absolute. For example:

◦ Primary.myEmbeddedPage
◦ StepPage.myEmbeddedPage
• You do not need to list all the clipboard pages expected to be on the clipboard,
only those that are referenced in this rule.
• For HTML rules, XML Stream rules, and other stream rules containing JSP tags, list
all the pages identified in the HTML text, including system pages ( pxRequestor ,
pxProcess , pxThread , and their embedded pages, if mentioned).
• You cannot use the keywords $ANY or $CLASS in the Class column.
• Do not use the keywords $ANY, $CLASS, or $None in the Class column; these
keywords are deprecated.
• If the Class column is blank, the Applies To class of the rule is used by default.

©2023 Pegasystems Inc

 Pega Platform 8.8 160

• For rules that run in the context of a primary page, you can leave the page name
blank for greater flexibility. (The class of the primary page matches the Applies To
key part of the rule.)
• You must have classes for data pages defined on the Pages & Classes tab. When
you add a parameterized data pages to the tab, do not use parameters or
brackets.

Note:

• The context at run time often differs from the context at design-time.
• You can enter rows in the list in any order.
• You cannot use the Top keyword in the Pages & Classes tab of a list view
or summary view rule.
• Using the Top keyword in a data transform does not reference the top-
level page.
• You must list embedded pages in the Pages & Classes tab if the class of
the embedded page varies from the class defined for the property at run
time.

Run-time processing

The pages that are present when a rule is running might vary from execution to
execution. The system neither requires nor checks that all the pages listed are present
each time it runs the rule. It only determines it can find the properties needed to
perform the current execution.

In some situations, the class of a page may vary from execution to execution. If all the
properties referenced are available in a common parent class, you can list the parent
on this tab, even though the page belongs to a subclass.

For example, an activity may operate on a page named Customer that, in some
situations, has the class Data-Account-Savings and in other cases has the class Data-

©2023 Pegasystems Inc

 Pega Platform 8.8 161

Account-Checking. If all the properties that the activity needs — for example
CurrentBalance and AccountOpenDate — are defined in the Data-Account- class, you
can list Data-Account- in the Class column.

However, if the activity needs to access both checking and savings data at once, the
activity needs to work with two pages — one of each class — with distinct page names.

Identifying pages in your application

Managing the number and names of clipboard pages referenced in your application is
important. Using too many pages or omitting to remove the pages when no longer
needed can add to the run time memory demand of your applications. Misspelling
page names or having two copies of one page (with different names) can also hurt
performance or make testing difficult.

Use the Data Designer Usage tab to see the pages that use a data type.

Special cases

Certain rule forms offer more capabilities for greater power and flexibility:

• This functionality is not supported. Use a data page instead. For three rule types
— Declare Expression, constraints, and when condition rules — you can define
page names that start with the keyword locate and that use an activity to
search or assemble the page needed. These pages are known as locatable pages.
• For six rule types — including activities and correspondence — pages with names
that start with the keyword prompt are known as indirect pages. This facility
allows a calling activity to share multiple pages with a called activity, for example.
When the called activity references a property on a page named promptALPHA,
the system searches the clipboard for a page named ALPHA.

Note: This feature has been deprecated.

©2023 Pegasystems Inc

 Pega Platform 8.8 162

• Using the Clipboard tool

Page names and reserved pages

A page is a data structure that holds name-value pairs.

Most pages are named; the names of pages may arise from any of four sources:

• Literal values entered into a rule such as a parameter to the Page-New method.
• System-created pages with reserved names and purposes, such as the requestor
page.
• Names used by convention in a collection of rules designed to operate together
• Property names (for embedded pages)

Valid page names

A page name can contain only letters, digits, and the underscore character. Start the
page name with a letter.

Several keywords identify elements in specific operations. Using keywords as a page

name is not recommended: param , local , locate (unsupported), primary ,
steppage , mysteppage , top , parent , or current .

Do not use any of the following names or patterns as a page name, where an asterisk
indicates one or more characters: pxNode , pxRequestor , pxThread , LISTVIEW_* ,
locate* prompt* , $* , px* , pz* , or py* .

Special page name prefixes

You cannot use certain prefixes and keywords as page names, as they have a special
meaning:

• local – Not a page, a keyword indicating that the name that follows the word
"local" and the period is a local variable, not a property.

©2023 Pegasystems Inc

 Pega Platform 8.8 163

• locate – A prefix to a page name (in lowercase), indicates that this page is
retrieved or located at runtime through an activity of type Locate . This prefix is
unsupported. Locatable pages have been replaced by data pages.
• mode – Identifies an indirect page reference.
• param – Identifies the parameter page for an activity. This page structure is not
part of the clipboard.
• parent – In the context of an embedded page, identifies the immediately
containing page to which the embedded page belongs. This keyword might
appear more than once in a property reference. You keyword is used in Declare
Index rules, decision tables, decision trees, and map values. You can also use the
PARENT keyword in the Step page field in activities. You cannot use this keyword
in data transforms.
• prompt – As a prefix portion of a page name, not a keyword, identifies an indirect
page reference in a Call or Branch.
• primary – In the context of an activity, refers to the primary page of that activity.
• top – In the context of an embedded page, identifies the top-level page to which
the current embedded page belongs.

The prefixes D_ and Declare_ in a page name indicates a data page, a page that is
created and updated only by data page rules. The properties on this page are "read-
only" to normal requestor processing. To avoid confusion with such pages , don't create
pages named Declare_zzzzz or D_zzzzz in other processing.

Except as noted, case is not significant in keywords: Param.Country, PARAM.Country

and param.Country all reference the same value.

Page names used by convention

Many standard activities and other standard rules use these page names by
convention. To utilize these standard rules, follow these naming conventions in the
rules you create.

©2023 Pegasystems Inc

 Pega Platform 8.8 164

Page Name Description

NewAssignPage When a single assignment object is open on

the clipboard, the page is named
NewAssignPage . If your application
involves multiple work items (or multiple
assignments) on the clipboard, you can use
other names.

pyCoverPage By convention in standard flow processing

activities, when a single cover work item is
opened onto the clipboard, the page is
named pyCoverPage .

pyOutput Created by Process API activities.

pyWorkPage By convention in standard flow processing

activities, when a single (non-cover) work
item is opened onto the clipboard, the page
is named pyWorkPage .

RuleToRun Created during unit testing of a rule with the

Run toolbar button. The class of this page
matches the rule type. See Unit testing a rule
with the Run toolbar button.

System-created pages

These top-level pages are present in the clipboard of every authenticated requestor:

Page Name Description

Process page ( pxProcess ) A named page of class Code-Pega-Process

containing system-wide information, such as
information from the Data-Admin-System
instance.

©2023 Pegasystems Inc

 Pega Platform 8.8 165

Page Name Description

Requestor page ( pxRequestor ) A named page of class Code-Pega-Requestor.

Created at log in and contains information
about your access roles, RuleSet list, and TCP
and HTTP protocol parameters.

Thread page ( pxThread ) A named page of class Code-Pega-Thread,

identifies a named context of clipboard
pages. The first Thread for a requestor is
named STANDARD .

AccessGroup Contains information from the requestor's

current access group (Data-Admin-Operator-
AccessGroup class). This page does not exist
for guest (unauthenticated) users.

Org Contains information from the requestor's

organization ( Data-Admin-Organization class).
This page does not exist for guest
(unauthenticated) users. This page does not
exist for guest (unauthenticated) users.

OrgDivision Contains information from the requestor's

organization ( Data-Admin-Organization class).
This page does not exist for guest
(unauthenticated) users.

OperatorID Contains information from the requestor's

Operator ID ( Data-Admin-Operator-ID class).
This page does not exist for guest
(unauthenticated) users.

©2023 Pegasystems Inc

 Pega Platform 8.8 166

Other

Page Name Description

pyQueryResultPage Produced by execution of a list rule ( Rule-

Obj-List rule type).

• Indirect pages
• Properties
• Clipboard tool
• Using the Clipboard tool

Rule skimming for higher ruleset versions

Skimming is an operation of copying rules from your rulesets into a ruleset of a higher
version. Skimming improves the performance of your application because the system
filters out rules that are unavailable for rule resolution. Because the new ruleset
contains only the highest rule versions, skimming simplifies rule resolution and
minimizes the rule data that you ship to a different version of your application.

Skimming collects the highest version of every rule in the ruleset and copies the rules to
a new major or minor version of that ruleset on the same system. Rule availability and
the type of skimming determine which rules the system carries to a higher ruleset
version.

You can select between a major skim and a minor skim. The skim type corresponds
with the digits in a ruleset version number. The two first digits define the major version,
and the two middle digits define the minor version. For example, in the ruleset version
06-09-10, 06 indicates the major version, and 09 corresponds with the minor version.
The major ruleset version typically specifies a release of your application or other
significant changes, while the minor version relates to an enhancement or a less
extensive change in your application. When you select a skim type, consider changes
that you want to merge in the higher ruleset version. The final two digits correspond
with patch releases and do not have a separate skim type associated with them.
Skimming copies rules so that all your rules in lower ruleset versions remain

©2023 Pegasystems Inc

 Pega Platform 8.8 167

unchanged. During skimming, the system omits rules in the major versions that are
lower than the major version that you specify. For example, if you opt to skim
02-05-02 into 03-01-01, the system ignores any rules in the version 01-XX-XX.

The following table displays which rules you can include in a higher ruleset version by
using either the major or minor skimming type:

Skim type/ Available Not Final Withdraw Blocked

Rule Available n
availability

Major Yes No Yes No Yes

Minor Yes No Yes Yes Yes

The update history of the new skimmed rule contains only one instance that reflects
the date and time of the rule creation based on the skim operation. The history of the
source rule is available and remains unchanged.

For relevant learning materials, see an Application versioning module on Pega

Academy.

Related concepts

• Organizing rules into rulesets

Related tasks

• Creating rulesets
• Defining the security of a ruleset
• Deleting a ruleset

©2023 Pegasystems Inc

 Pega Platform 8.8 168

Creating higher ruleset versions by skimming rules

Improve the performance of your application and simplify the rule resolution by
skimming rules to create higher version rulesets. Skimming filters out rules that are not
available for rule resolution and makes rule management more convenient.You can
select between two types of skimming, a minor skim and a major skim. The minor skim
moves rules to a higher minor version of your application, for example, after you
implement new enhancements. You can check the minor ruleset version by analyzing
the middle two digits of the ruleset version. An example of a minor skim is skimming
rules in 06-05-01 through 06-09-25 into the 06-10-01 ruleset versions. The major
skim moves rules into a higher major version of your application, such as a new release.
The two first digits in the ruleset version correspond with the major version. A major
skim is skimming rules 06-05-01 through 06-09-25 into the 07-01-01 ruleset
versions.

Before you begin:

• Check in all the rules that you want to skim. For more information, see
Checking in a rule.
• To ensure that users cannot edit lower versions of the ruleset after
skimming, secure the lower ruleset versions. For more information, see
Defining the security of a ruleset.

During skimming, the system copies rules to a new ruleset with a higher version
number. The rules in the lower versions remain unchanged in your system.

1. In the header of Dev Studio, click Configure > System > Refactor > RuleSets.
2. On the RuleSets tab, in the Refactor Rulesets Utilities section, click Skim a
Ruleset.
3. In the Skim to create a higher version window, define the skimming settings:

©2023 Pegasystems Inc

 Pega Platform 8.8 169

Choices Actions

Perform a major skim a. Select the Major Version RuleSet

Skim radio button.
b. In the RuleSet list, select a ruleset
that you want to skim.
c. In the From Major Version list, select
an existing major version that you
want to skim to a higher version.
d. In the To New Version field, enter a
ruleset version that you want to
create with skimming.
Ensure that the new version relates
to the skimming type.

For example:

If you want to perform a

major skim on the 06-09-25
version, enter 07-01-01.

e. Click Skim.

Perform a minor skim a. Select the Minor Version RuleSet

Skim radio button.
b. In the RuleSet list, select a ruleset
that you want to skim.
c. In the Starting Version and Ending
Version lists, select a version range
of the ruleset that you want to skim.

©2023 Pegasystems Inc

 Pega Platform 8.8 170

Choices Actions

For example:

Select 06-05-01 as a start

version and 06-09-25 as an
end version.

d. In the To New Version field, enter a

ruleset version that you want to
create with skimming.
Ensure that the new version relates
to the skimming type.

For example:

If you want to perform a

minor skim on the
06-05-01 to 06-09-25
version range, enter
06-10-0.

e. Click Skim.

Result:

The window displays the progress and the results of the skim after the
process is complete.

4. If any errors occur, click the Total Errors link.

You can only access the list of errors from the Skim to create a higher version
window.

©2023 Pegasystems Inc

 Pega Platform 8.8 171

What to do next:

• Research and resolve errors that occurred during the skim operation.
• Update access groups or application rules to make the new major version
available to appropriate users. For more information, see Learning about
access groups.
• To ensure that users can edit only the highest ruleset version, secure lower
ruleset versions. For more information, see Defining the security of a
ruleset.
• To decrease the number of rules in your system and speed up rule
resolution, delete rules in the lower major versions. For more information,
see Deleting a ruleset.

Note: Ensure that your organization accepts deleting rules that

are no longer in use.

• Organizing rules into rulesets

• Creating rulesets

Adding a custom field

Associating custom fields with rules provides a flexible way to supplement your
application with metadata, such as a change order number or log file attachment.

To add a custom field, do the following.

1. Click the History tab of a rule form.

2. Click Add Field to open the Add custom fields dialog.
3. Choose a name from the list of properties to populate the Name field.
Alternatively, enter a string (letters and digits only) directly in this field to create a
new property with the specified name.

©2023 Pegasystems Inc

 Pega Platform 8.8 172

4. If you entered a string in the Name field, select a Type for the property. For
existing properties, this field is populated and read-only.
5. From the RuleSet version drop-down box, select the appropriate ruleset version.
• For properties of Type File:
• Enter a brief description of the file in the Description field.
• Select the New or Existing radio button to indicate how you will provide
the file.
• Click Browse to upload a file from your local system. The file you
specify becomes an instance of Rule-File-Binary.
• Click the Pick a file button to select a file previously linked to this
property.
• For properties of Type Text:
◦ Enter text to pair with the property in the Value field.
◦ Alternatively, click the Open icon to select a value previously applied
to this property.
6. Click Submit to close the dialog.
7. Click Save in the rule form header to persist your changes. The Custom Fields list
is automatically updated by the rule form.

• Viewing rule history

Preparing for modifying rules

Adjust your application to your unique business scenario by modifying existing rules. As
a result, you save resources, such as time and money, and deliver software that
precisely meets your business requirements. You can also delegate a rule so that non-IT
stakeholders can perform needed changes.

Before you modify a rule, you need to check out the rule to ensure that no other
developer modifies the same rule at the same time. If your business requirements
change, you can revert to the previous state of the rule, or completely delete the rule.

• Checking out a rule

©2023 Pegasystems Inc

 Pega Platform 8.8 173

• Restoring the earlier state of a rule

• Creating guidance for developers

• Delegating a rule or data type

• Deleting a rule

Checking out a rule

To avoid accidental rule changes or conflicts that might result from multiple developers
working on the same rule, perform a check out, so that you can lock the rule and safely
make changes to it. By checking a rule out before editing, you avoid unwanted rule
changes, and as a result save time and maintain a better quality application.

You can only check out rules that belong to an unlocked ruleset. If you want to edit a
rule that belongs to a locked ruleset, perform a private edit. For more information, see
Performing a private edit.

Note: When you make updates to your application in App Studio, Pega
Platform automatically manages the check-in and checkout process.

1. In the navigation pane of Dev Studio, click Records, expand the category that
contains the rule that you want to edit, and then click the rule.
2. In the header of the rule form, click Check out.
Your application places a copy of the original or base rule in your personal ruleset.
No other user can check out this rule until you check in your changes.
3. Modify the rule as appropriate.
4. Click Save.
Your application saves your changes into the checked-out version of the rule.
These changes are visible only to you. When you run rules in your application,
they resolve to only your checked-out version.

©2023 Pegasystems Inc

 Pega Platform 8.8 174

What to do next:

Make your changes available to other developers of your application by checking

in the rules that you edit. For more information, see Checking in a rule.

Note: You do not have to check in your changes immediately. You can
log out and return to a checked-out rule later or click Discard to remove
the rule from your personal ruleset.

• Standard rule checkout

• Performing a private edit

• Checking out a rule to a branch

• Viewing your checkouts and accessing bulk actions

• Rule checkout notes

• Rule checkout tips

• Personal ruleset

• Checking in a rule

• Rule check-in process

Standard rule checkout

The Check out button appears for standard checkouts when all the following criteria
are met:

• The rule belongs to a ruleset that has the checkouts enabled.

©2023 Pegasystems Inc

 Pega Platform 8.8 175

• For this operator, the Allow rule check out check box on the Security tab of the
Operator ID form is selected.
• The rule is not locked by another user or in a locked ruleset. A locked rule displays
a padlock next to the Check out button. Click this icon to see the reason it is
locked.

Other operators can use Check out to branch or Private edit until you release the lock.

• Checking out a rule

Performing a private edit

To ensure that your application meets the unique needs of your customers, you can
modify a rule that is unavailable for regular checkout by performing a private edit.
Check out rules as private edits to edit rules that belong to locked rulesets.Private edits
are useful for quick debugging without interrupting other team members, because
during a private edit other system architects can edit a rule at the same time.

Before you begin:

• Ensure that you have the pxAllowPrivateCheckout privilege, which is typically

granted through a role on your access group. The standard access role
PegaRULES:SysAdm4 provides this privilege.
• Ensure that the rule is not available for regular checkout, usually because
the rule is already checked out to another user or because its ruleset
version is locked.
• Ensure that the rule belongs to a ruleset that has the checkouts enabled.
• Ensure that your Operator ID is allowed to check out rules. For more
information, see Defining security information for an operator.

When you perform a private edit, you edit a rule in an isolated sandbox, in which you
can make and then test your changes. As a result, you maintain a good quality

©2023 Pegasystems Inc

 Pega Platform 8.8 176

application and avoid creating errors, because during a private edit the original ruleset
that contains your rule remains unchanged.

1. In the navigation pane of Dev Studio, click Records, expand the category that
contains the rule that you want to edit, and then click the rule.
2. In the rule form, click Private edit.
3. In the dialog box that appears, click Continue with private edit.
The system saves a copy of the rule in your personal ruleset. Rules in your
personal ruleset do not affect other users’ run-time experiences, or the actions
that they can perform on this rule.
4. Edit the rule.
5. Click Save.
Your application saves your changes into the checked-out version of the rule.
These changes are visible only to you. When you run rules in your application,
they resolve to only your checked-out version.

What to do next:

Make your changes available to other developers of your application by checking

in the rules that you edit. For more information, see Checking in a rule.

• Checking out a rule to a branch

Checking out a rule to a branch

You can check out a rule to a branch so that you can make changes to a rule and then
save it in the branch ruleset. For information about rule resolution for rules saved to a
branch ruleset, see Rule resolution exceptions.

Because you cannot make changes to rules in a locked ruleset, you can check out a rule
to a branch in your application, make changes, and then check the rule in to your
branch. You can also perform a private checkout.

©2023 Pegasystems Inc

 Pega Platform 8.8 177

1. In the ruleform toolbar click Check out to branch, if available. Otherwise, click the
arrow on the Private edit button and select Check out to branch.
2. From the Branch list, select a branch and click Check out to branch.
The system saves a copy of the rule to the selected branch ruleset and then
checks it out.
3. Modify the rule as appropriate.
4. Click Save.
5. Check in the rule. For more information, see Checking in a rule.

Note: You do not have to check in your changes immediately. You can
log out and return to a checked-out rule later or click Discard to remove
the rule from your personal ruleset.

If you discard the checked-out version, the original copy of the rule remains in the
branch ruleset.

• Performing a private edit

Viewing your checkouts and accessing bulk actions

Click the Checkouts icon in the Dev Studio header to open a list of rules checked out by
your operator. Rules are organized by type, name, and Applies To class.

In the Private overlay, you can perform the following actions:

• Click any rule type to see only checked-out rules of that specific type.
• Click any rule name to open the rule.
• Expand any row to see all versions of the checked-out rule.
• Click the Type or Name columns to sort the list.
• Use the filter icon in the Type and Name columns to apply more specific filter
criteria.

©2023 Pegasystems Inc

 Pega Platform 8.8 178

• Open, delete, or check out multiple rules at once using bulk actions by clicking the
Bulk actions link. A list of rules checked out by your operator appears in a new
window.

• Standard rule checkout

• Checking in rules in bulk

Discarding checked out rules in bulk

Maintain the best quality application by discarding checked out rules that are irrelevant
to your development projects. To save time, you can discard multiple rules at once by
performing a bulk action.

Before you begin:

Check out rules that you want to edit. For more information, see Checking out a
rule.

1. In the header of Dev Studio, click the Checked out records icon.
2. In the Checked out records window, click Bulk actions.
3. In the window that appears, select the check box next to one or more rules that
you want to discard.
4. In the list at the bottom of the window next to the Start button, select Discard.
5. Click Start.

Result:

The Status column shows the results of your bulk discard.

• Viewing your checkouts and accessing bulk actions

Opening checkouts in bulk

To open checkouts in bulk, complete the following steps:

©2023 Pegasystems Inc

 Pega Platform 8.8 179

1. Click the Checked out records icon in the Dev Studio header and then click
Bulk actions.
2. Select the check box next to one or more rules.
3. Select Open from the list at the bottom of the window next to the Start button.
4. Click Start.
5. Wait for the lock icon to appear in the Status column next to each selected rule
name.
6. Review each opened checkout. If you do not have checkouts enabled, open the
Recent Explorer to access each checkout.

• Viewing your checkouts and accessing bulk actions

Rule checkout notes

Note the following information when you are checking out rules:

• A checked-in rule version can have validation errors, which can occur when ruleset
prerequisites change or a referencing rule is relocated. When you perform a
standard checkout, the validation errors appear in the rule form header. You must
resolve all errors and save before you can check in any new changes.
• You cannot check out a base rule when you or another developer has a
circumstance version checked out.
• You cannot check out the following rule types:
◦ Application
◦ Class
◦ Ruleset version
◦ Library
◦ Agent
◦ Application settings

• Standard rule checkout

©2023 Pegasystems Inc

 Pega Platform 8.8 180

Rule checkout tips

You can use several features to determine that you have checked out all the rules in
your application You can also use other features to undo changes and to override the
default check-in procedure.

Refer to the following list for tips about rule checkout.

• Click the Checked out records icon in the Dev Studio header to view all the
rules that you have checked out.
• Use the Application Development landing page to view all checked-out rules. Rules
checked out using the Private edit option do not appear in this list.
• Use the restore feature to undo changes made by a checked-in version.
• Use the Rule-.SetApprovalDependency activity to override the default check-in
procedure.
• Use the lock icon to see who has a specific rule instance checked out.
• Select the View version > Checked out from [ version number ] option in the
Actions menu to view the base version of the rule that you checked out.

• Standard rule checkout

• Viewing your checkouts and accessing bulk actions
• Restoring the earlier state of a rule

Personal ruleset
Users who have the Allow rule check out option enabled for their operator IDs can
place copies of rule instances into a personal ruleset. The name of this ruleset is the
Operator ID, such as john_sawyer@abc.com. The personal ruleset is sometimes called
the private ruleset.

Personal rulesets are used in with the checkout and check in features. The system
creates a personal ruleset automatically when needed. No instance of the Rule-RuleSet-
Name class exists for this ruleset. Rules in a personal ruleset are never run by other
users.

©2023 Pegasystems Inc

 Pega Platform 8.8 181

On the requestor page, the standard property

pxRequestor.pxSecuritySnapshot.pxPersonalRuleSetName identifies the personal ruleset. If
this property is blank, the requestor cannot check out rules.

A memory cache contains rules in your personal ruleset. The maximum size of this
cache (for all developers combined) is determined by elements in the fua node of the
prconfig.xml file or by dynamic system settings.

• Learning about access groups

Checking in a rule
To make your changes available to your development team after you check out and edit
a rule, check in the rule. When you check in edited or updated rules, you contribute to
the efficient development of your application and avoid errors that might occur when
other developers work on the same rule.

Before you begin:

Check out, and then update a rule. For more information, see Checking out a
rule.

CAUTION: Use caution when you check in rules after you perform a
private edit, because you may overwrite changes from other
developers. For more information about private check out, see
Performing a private edit.

1. In the navigation pane of Dev Studio, click Records, expand the category that
contains the rule that you want to check in, and then click the rule.
2. In the header of the form, click Check in.
3. If you perform a check in after a private edit, in the Check In window, in the
Destination section, specify where you want to save the rule:

©2023 Pegasystems Inc

 Pega Platform 8.8 182

• To save a rule to an unlocked ruleset, select Ruleset, and then specify a

ruleset and a ruleset version.
• To save a rule to a branch, select Branch, and then specify the branch.

Note: Checking in a private edit to a branch could result in loss of work if

another user checks in changes to the same rule. You receive a warning
message if your check-in might result in lost work.

4. In the Check-in comments field, enter a comment that describes your changes to
the rule.
5. Optional: To override the default work item that your application associates with
this development change, press the Down arrow key in the Work item to associate
field, and then select a work item.
For more information about your default work item, see Setting your current work
item.
6. Click Check in.

Result:

If your edits do not require approval, your changes immediately affect rule
resolution and run-time behavior for all users.

• Configuring the rule check-in approval process

• Rule check-in process

• Checking in rules in bulk

• Checking out a rule to a branch

• Checking out a rule

©2023 Pegasystems Inc

 Pega Platform 8.8 183

Configuring the rule check-in approval process

To turn on controlled check-in for a ruleset, complete the following tasks:

1. Enable checkout features for the ruleset by selecting the Use check-out? box on
the Security tab of the ruleset form.
2. Enable the checkout feature for each development team member by selecting the
Allow rule checkout box on the Security tab of each member's Operator ID form.
3. On the Security tab of the ruleset form, specify both key parts of the flow that is to
control the rule check-in approval process. Specify the flow's work class in the
Work class used for approval process field and the name of the flow in the Work
flow to use for approvals field. Your system includes a standard work type Work-
RuleCheckIn, standard properties and activities, and a standard flow named
ApproveRuleChanges to use for this feature. You can use the standard rules as is, or
copy and adapt them.
4. Review (and override if desired) the standard decision tree named Work-
RuleCheckIn.FindReviewers to identify the work queues used in this flow. If
overriding the standard rule, create the new decision tree in the ruleset and
version being developed by the team.
5. Update the access group associated with those reviewers you want participating
in the rule check-in approval process to include the standard Work-RuleCheckIn
work pool in the access group's Work Pools list.
6. Create a work queue named ReviewChanges@ org.com or others identified
in the decision tree. Update the Operator ID data instances for each reviewer to
allow them to access the work queues.
7. Associate the standard access role PegaRULES:SysAdm4 (or another role with
the privilege Rule-.UpdatePrivateRuleSets ) with each Operator ID data instance who
will approve check-ins.
8. Update the standard ruleset CheckInCandidates (version 01-01-01) to identify an
appropriate prerequisite RuleSet.
9. Add this ruleset (version 01-01-01) to the access group of those developers who
are to approve check-ins.

©2023 Pegasystems Inc

 Pega Platform 8.8 184

10. For each version you want to enable with this process, select Yes in the Approval
Required field on the Versions tab of the ruleset form.

Rule check-in process

The optional rule checkin facility allows you to use a Pega Platform flow rule to manage
change to your application. Use this facility to coordinate the efforts of large
development teams or to control changes to sensitive applications.

See Configuring the rule check-in approval process for information about setting up
controlled check-in for a ruleset.

When this facility is in force for a ruleset version, the flow starts when a developer
begins rule check in.

The flow creates a work item that is routed to a work queue, waiting for an approver to
review.

The approver might approve the check-in (which completes the check in), reject it
(which deletes the changed rule), or send it back to the developer for further work.

Assignments corresponding to rules awaiting evaluation are held in the

ReviewChanges@org.com work queue.

Multiple rules can be associated with one work item. The flow rule notifies affected
parties by email about evaluation results.

When uploading approved rules, select the following Import Options: Compile Libraries,
Overwrite Existing Rules, Overwrite Existing Data.

You can enhance this process to meet local requirements in various ways. For example,
certain empty (dummy) activities are called by this flow; your application can override
these with desired processing.

©2023 Pegasystems Inc

 Pega Platform 8.8 185

Checking in rules in bulk

Save time and improve your management of the rules that you edit in your application
by performing a bulk check-in. When you perform bulk actions, you can view all of the
rules that are currently checked out in your application, and then you can check in
several rules at once.

Bulk check in supports only rules that you check out through the standard checkout
procedure. For information about checking in rules after a private checkout, see
Performing a private edit.

1. In the header of Dev Studio, click the Checked out records icon.
2. In the Checked out records window, click Bulk actions.
3. In the window that appears, select the check box next to one or more rules that
you want to check in.
4. In the Check-in comments field, enter a brief description of your changes.
5. Select CheckIn from the list next to the Start button at the bottom of the window.
6. Optional: To apply one prefix to all comments, in the Bulk Prefix field, enter the
text, and then click Insert.
7. Optional: To override the default work item that your application associates with
this development change, press the Down arrow key in the Work item to associate
field, and then select a work item.
For more information about your default work item, see Setting your current work
item.
8. Click Start.

Result:

The Status column shows the results of your bulk check in.

• Viewing your checkouts and accessing bulk actions

©2023 Pegasystems Inc

 Pega Platform 8.8 186

Restoring the earlier state of a rule

During application development, you can undo recent changes to a rule and replace the
current rule with a previous copy, even if another developer created the newer copies.

Before you begin:

Ensure that you have the @baseclass.ToolbarFull privilege.

When you resotre a rule, consider the following circumstances:

• You do not need to use the Restore operation to fall back to a rule instance that is
in a lower-numbered version. Use the Delete toolbar button to delete the current
higher-numbered version or versions that mask or override a lower-numbered
version.
• If you want to change the lower numbered version but the version is locked, use
Save As, not Restore, to copy — promote — an older version to the current
unlocked higher version.

1. Open the current version of the rule.

2. Click the History tab.
3. Click the View full history button to view a list of snapshots in a new window.
4. Details display that contains the state you want. Click the rule history button to
open the older, historical state of this rule instance. The padlock image indicates
that this is not the current rule, not that the rule is checked out to you.
5. Click the Restore button for the state that you want to make current.

• Recovering a deleted rule

Creating guidance for developers

Create internal documentation to provide guidance to the developers who implement
or extend your application.

©2023 Pegasystems Inc

 Pega Platform 8.8 187

Use the following techniques to create internal documentation:

• Creating project documents for stakeholders in Dev Studio

• Creating a guide for application developers and administrators

Adding usage information to a rule

Add usage information to a rule to help developers decide whether they can reuse the
rule in their features or applications.

As a best practice, provide usage information when you create a rule.

1. Open a rule by searching for it or by using the Application Explorer.

2. Click the History tab.
3. In the Documentation section, enter text in the Description field that describes
the purpose of your rule.
4. In the Usage field, enter text that helps developers understand how to use this
rule.

For example, you can describe the expected inputs and outputs.

5. Click Save.

• Adding historical information to a rule

• Setting rule status and availability
• Adding a custom field

Adding historical information to a rule

Describe the recent changes to a rule in the rule history to help developers trace your
implementation and compare versions more quickly.

1. Open a rule by searching for it or by using the Application Explorer.

2. On the History tab, click View full history.
3. Click History For All Versions.

©2023 Pegasystems Inc

 Pega Platform 8.8 188

4. In the Add Memo field, enter text that describes the differences between this
version of the rule and the prior version.
5. Click Add Memo.

• Viewing rule history

• Comparing rule versions

Delegating a rule or data type in Constellation

Enable your business line to configure simple application logic without involvement
from IT by delegating a rule or data type in your Constellation application.

For example, you can delegate a decision table to a business line manager. The line
manager views the decision logic in a familiar environment, such as the Case Manager
portal, and can update it as a stand-alone item without knowing all the related technical
details.

You enable rule delegation in your Constellation application by adding a Theme

Cosmos page to the Constellation application navigation pane.

Before you begin:

Prepare the applications that you want to integrate:

• Ensure that both the traditional application and the Constellation

application have the same name but different version numbers.
• Ensure that both applications use single sign-on (SSO) authentication. For
more information, see Creating an authentication service.

• Create an activity that opens a harness in a new browser tab to use for the
integration. For more information, see Creating an openHarness activity.

• Rule and data type delegation

• Modifying a delegated record or data type

©2023 Pegasystems Inc

 Pega Platform 8.8 189

• Creating a data object

Configuring URL mapping for the Configuration landing page

Create an alias for the Configuration landing page, which contains delegated rules and
data types. You configure this mapping in the Theme Cosmos application so that you
can access the landing page in your Constellation application.

1. Log in to your Theme Cosmos application.

2. In the navigation pane of Dev Studio,click Records.
3. Expand the Technical category, and then click URL Mappings.
4. In the list of URL mapping rule instances, open the top-most rule for your
application: pyDefault.
5. In the Landing pages section, click Add URL alias.
6. In the Define URL mapping dialog box, configure the URL path:
a. In the Identifier field, enter OpenConfiguration.
b. In the Class field, enter Work-.
c. In the Path element type list, select Constant.
d. In the Value field, enter configuration.
e. Click Next.

Result:

The following figure shows the URL mapping settings for the
OpenConfiguration URL alias:

©2023 Pegasystems Inc

 Pega Platform 8.8 190

The settings for the new OpenConfiguration URL mapping

7. In the Define processing activity dialog box, configure the activity that starts
when the user opens the URL:
a. In the Class field, enter Work-.
b. In the Activity field, enter openHarness.
c. Click Add parameter, and then in the Parameter field, enter tabName.
d. In the Value field, enter Configuration.
e. Click Add parameter, and then in the Parameter field, enter className.
f. In the Value field, enter Data-Portal.
g. Click Add parameter, and then in the Parameter field, enter ruleName.
h. In the Value field, enter DelegatedRulesPage.

©2023 Pegasystems Inc

 Pega Platform 8.8 191

Result:

The following figure shows the activity mapping for the OpenConfiguration
URL alias:

The settings for the OpenConfiguration activity mapping

8. Click Finish.

Delegating a rule or data type

Enable your business line to configure simple application logic without involvement
from IT by delegating a rule or data type.For example, you can delegate a decision table
to a business line manager. The line manager views the decision logic in a familiar
environment, such as the Case Manager portal, and can update it as a stand-alone item
without knowing all of the related technical details.

©2023 Pegasystems Inc

 Pega Platform 8.8 192

Before you begin:

Note: Standard Pega Platform applications support rule delegation out

of the box. To enable rule delegation in applications that you build on
Constellation, see Delegating a rule or data type in Constellation.

You can delegate a paragraph, decision table, data type (configured for local storage),
map value, correspondence, or service-level agreement (SLA), including circumstance
types.

1. Open the rule or data type that you want to delegate.

2. From the Actions menu, click Delegate.
3. Select how the end user will interact with the delegated rule.
The options that are displayed depend on the rule or data type that is being
delegated.
• Manage content – Users can modify the content of decision tables, map
values, paragraphs, and correspondence rules.
• Manage content and modify table – For map values, users can add, modify,
or delete rows and columns in the map value table in addition to modifying
contents.
• Manage data records – For data types, users can add, modify, or delete data
entries for the data type.
• Manage SLA – For SLAs, users can configure goals, deadlines, and escalation
actions.

Note: You cannot delegate SLAs on which service levels are

calculated by the value of a property.

©2023 Pegasystems Inc

 Pega Platform 8.8 193

Note: If you later modify a delegated SLA in Dev Studio to have

service levels calculated by the value of a property, users cannot
modify the Days or hh:mm fields or select the Calculate using
business days checkbox for the Goal, Deadline, or Passed Deadline
sections.

Note: When users modify SLAs in the Case Manager, they can
select only Notify Manager or Notify Assignee as escalation actions.
If you change the escalation action in Dev Studio to anything other
than these actions, users cannot modify escalation actions.

4. In the Delegate to access group drop-down list, press the Down arrow and select
the access group to which you want to delegate the rule or data type.
5. In the Title field, enter a title for the delegated rule or data type.
6. In the Detailed Description field, enter detailed information about the delegated
rule or data type. This text is displayed to the user.
Provide information about how the delegated rule or data type will affect the
application. For example, "The logic in this delegated decision table determines
whether a travel request required additional manager approval. Changing the
logic in this decision table may affect all subsequent travel requests submitted in
this application."
7. Click Delegate.

Result:

Users can access delegated rules and data types from the Case Manager portal.
Users can also access data types in App Studio.

• Delegating a rule or data type in Constellation

• Delegating a data type

©2023 Pegasystems Inc

 Pega Platform 8.8 194

• Rule and data type delegation

• Prerequisites for delegating a rule or data type

• Best practices for delegating a rule or data type

• Modifying a delegated record or data type

• Configuring ruleset update behavior

• Rule and data type delegation

• Modifying a delegated record or data type
• Creating a data object

Overriding the pyIsAutoGenThread

Ensure that the mapped URL address of the target traditional landing page opens
correctly in a portal by adjusting the pyIsAutoGenThread when rule.

1. In the traditional UI architecture application, in the header of Dev Studio, search

for and open the pyIsAutoGenThread when rule.
2. On the Advanced tab of the rule form, define the new logic for the when rule:
a. To the right of the row A of the condition, click the Configure advanced
conditions here arrow.
b. In the list of logic structures, select [condition evaluates to true].
c. In row A, enter
@String.contains(@toUpperCase(pxThread.pxThreadName),@toUpperCase("au

For example:

©2023 Pegasystems Inc

 Pega Platform 8.8 195

When rule configuration and the advanced conditions arrow

3. On the rule form, click Save as.

4. On the New tab, ensure that the context points to the application ruleset and the
@base class, and then click Create and open.

Adding the Configuration landing page to the navigation pane

Enable users of your Constellation application to access delegated rules and data types
by adding the Configuration landing page to the navigation pane.

1. Open the Constellation application.

2. In the header of Dev Studio, search for and open the
pyPopulateAdditionalNavPages data transform.
3. Optional: To limit the visibility of the Configuration landing page to a specific
group of users, add a when condition step to the data transform:
a. Create a HasDelegatedRules when condition that applies to the Code-Pega-List
class.
For more information, see Creating a When rule.
b. On the Pages & Classes tab of the when condition, in the Page name field,
enter DelegatedRules, and in the Class field, enter System-User-
MyRules.
c. On the Conditions tab of the when condition, set the following condition:
@(Pega-

©2023 Pegasystems Inc

 Pega Platform 8.8 196

RULES:Utilities).SizeOfPropertyList(D_pzFilteredDelegations.pyInstanc
> 0.
d. Back on the Definition tab of the pyPopulateAdditionalNavPages data
transform, click Add a row.
e. In the Action list, select When.
f. In the Target field, enter HasDelegatedRules.
4. On the Definition tab, click Add a row, and then define the parent row for the logic
that appends the Theme Cosmos page to the navigation menu:
a. In the Action list, select Append and Map to.
b. In the Target field, enter Primary.pxResults.
c. In the Relation list, select a new page.
5. Under the Append and Map to action, add and configure the first child action that
defines the label for the Theme Cosmos page:
a. In the Action list, select Set.
b. In the Target field, enter .pyLabel.
c. In the Relation list, select equal to.
d. In the Source field, enter "Configuration".
6. Copy the URL of the Theme Cosmos application:
a. In the header of Dev Studio, click the name of the application, and then click
Definition.
b. In the Application URL alias section, select and then copy the application
URL to the clipboard.
7. On the rule form of the pyPopulateAdditionalNavPages data transform, under the
Append and Map to action, click Add a row, and then configure the second child
action that defines the URL address for the Theme Cosmos page:
a. In the Action list, select Set.
b. In the Target field, enter .pyURLContent.
c. In the Relation list, select equal to.
d. In the Source field, enter the application URL that you copied in step 6 and
the URL path that you mapped in steps 1 through 8.

©2023 Pegasystems Inc

 Pega Platform 8.8 197

8. Under the Append and Map to action, click Add a row, and then configure the
third child action that defines the menu icon for the Theme Cosmos page:
a. In the Action list, select Set.
b. In the Target field, enter .pxPageViewIcon.
c. In the Relation field, list equal to.
d. In the Source field, enter "pi pi-case-solid".

Result:

The following figure shows the configuration for the

pyPopulateAdditionalNavPages data transform without an additional when
condition that limits the visibility of the Configuration landing page to a
specific group of users:

Configuration of the pyPopulateAdditionalNavPages data transform

Result:

Users of your Constellation application can access delegated rules and data
types from the Case Manager portal. Users can also access data types in App
Studio.

Delegating a data type

You can delegate a data type so that other users can modify records in local data
storage tables.

©2023 Pegasystems Inc

 Pega Platform 8.8 198

1. Click Turn editing on.

2. In the navigation panel, click Data to view the list of current data types in your
application.
3. Select the data type that you want to delegate.
4. On the Settings tab, select the Allow selected users to modify records check box.
5. Select the role of the users that you want to let modify records.
6. Click Done.

• Modifying a delegated record or data type

• Creating a data object

Rule and data type delegation

You can delegate a paragraph, decision table, data type (configured for local storage),
map value, correspondence, or service-level agreement (SLA), including circumstance
types, to your business line to bring less-technical stakeholders closer to your
application development. Users access these delegated rules and data types from the
Case Manager portal. Users can also access data types in App Studio.

Note: Only standard Pega Platform applications support rule delegation.

Applications that you build on Constellation do not support this feature.

Rule delegation allows the business line to configure simple application logic without
involvement from IT. For example, you can delegate a decision table to a business line
manager. The line manager views the decision logic in a familiar environment, such as
the Case Manager portal, and can update it as a stand-alone item without knowing all
of the related, technical details.

• Delegating a rule or data type

• Modifying a delegated record or data type
• Map Values
• Decision tables

©2023 Pegasystems Inc

 Pega Platform 8.8 199

Prerequisites for delegating a rule or data type

Before delegating a rule or data type, ensure that you certain requirements, such as
having the appropriate permissions.

Ensure that the following prerequisites are met:

• The rule or data type you are delegating is not a checkout.

• The rule you are delegating is not in a Pega ruleset.
• You have the pxCanDelegateRules privilege, which grants you the ability to delegate
rules and data types that are visible to users outside of your access group.
• The rules you are delegating are in an unlocked ruleset accessible to end users.

• Delegating a rule or data type

• Rule and data type delegation

Best practices for delegating a rule or data type

To successfully delegate a rule or data type to less-technical business users, you should
follow certain best practices.

When you delegate rules or data types, you should:

• Choose titles and descriptions that are meaningful in a business context.

• Isolate delegated rules in a separate, unlocked ruleset that does not require
checkins or checkouts. This insulates the rest of your application, which typically
resides in locked rulesets, from frequent changes made by managers to other
delegates.
• Provide appropriate training and documentation to line managers.
• If you delegate a rule or data type and then rename the class, you must re-
delegate the class.

• Delegating a rule or data type

• Rule and data type delegation

©2023 Pegasystems Inc

 Pega Platform 8.8 200

Modifying a delegated record or data type

You can modify records or data types that are delegated to you by developers. By using
delegation, you can change the functionality of your application without involving
additional staff members, such as database administrators and information technology
professionals. For example, you an modify the body of an email template or delete an
entry from a list of customer addresses.

1. In Case Manager the left navigation pane, click Configuration.

2. To filter items by keywords, enter text in the search field.
3. Click Edit to modify a delegated item.
The type of information you can modify depends on the type of item and the
options selected at the time of delegation.
4. Click Check Out for a checked-in item to create a copy of the record in your
personal ruleset. No one else can check out a record while it is checked out. The
Check Out button appears when all of the following conditions are true:

• The record belongs to a ruleset that has checkouts enabled.

• For the operator, the Allow rule check out check box (on the Security tab of
the Operator ID form) is selected.

• The record is not locked by another user or in a locked ruleset.

5. Click Check In for a checkout in your personal ruleset to copy the modified
instance over the original instance in the public ruleset. This action also releases
the lock so other operators can use the Check out action.
6. Click Discard to delete a checked-out record from your personal ruleset. The
original, unchecked-out record is not affected.
7. Click Save.

• Delegating a data type

©2023 Pegasystems Inc

 Pega Platform 8.8 201

Configuring ruleset update behavior

You can configure when users see new ruleset lists due to changes of access groups or
applications: immediately, at the start of the next thread, or at the next session.

By default, a session's ruleset list changes immediately when the session's access group
or application changes. You can configure your server to change the ruleset list at the
start of the next thread or session.

1. Configure the prconfig/Authorization/RSLUpdateBehavior/default dynamic system

setting (DSS) with the owning ruleset Pega-Engineand a value that reflects how you
want the ruleset to update:
• Immediate
◦ The default setting.
◦ Ruleset lists are updated as application and access group changes are
made.
• Threadset
◦ Ruleset lists are updated from application and access group changes at
thread creation boundaries and stay the same for the entire lifetime of
the thread.
◦ Thread creation boundaries include thread creation and thread switch
events.
• Fixedreq
◦ Snapshots of the ruleset lists are taken for all available applications at
login.
◦ Fixed throughout the lifetime of the session.
◦ If a requestor with the ruleset list update behavior that is set to
Fixedreq spawns a child requestor, the child requestor gets the most
recent context using their parent's access group as a key.
For more information, see Creating a dynamic system setting.
2. Restart the server.

• Configuring dynamic system settings

©2023 Pegasystems Inc

 Pega Platform 8.8 202

• Changing node settings by modifying the prconfig.xml file

Deleting a rule
Save disk space by deleting rules that are no longer relevant in your application. For
example, during application development, you create a field property to capture a
phone number, but later you need to capture multiple phone numbers. You create a list
property, and then delete the field property. As a result, you improve the extensibility
and user understanding of your application by providing only the rules that your
application requires.

Note: After you ship a ruleset, withdraw or block a rule instead of deleting it.
You cannot search for deleted rules.

When you develop a process in App Studio, your application might create additional
rules, such as views, that the final process does not require to function correctly. To
ensure that you deliver only the minimum number of rules that your application
requires, remove such unnecessary rules.

The following conditions can prevent you from deleting a rule:

• You cannot delete a rule that belongs to a locked ruleset version. However, in
most situations, you can create a blocked or withdrawn rule in your application
that masks a rule (makes invisible to rule resolution), that you no longer need in
your application.
• You cannot delete standard rules because they are part of the Pega Platform™
product. However, you can override many standard rules.
• You can delete a rule or data instance only in the following circumstances:
◦ If an Access of Role to Object rule that is associated with your access role
allows you to delete rules or data instances.
◦ If no Access Deny rules that are associated with your access role prevent you
from deleting rules or data instances.

©2023 Pegasystems Inc

 Pega Platform 8.8 203

• You cannot delete a rule in which the Circumstance or Start Time fields are blank if
your system contains other rules with identical keys that are circumstance-
qualified or time-qualified. Delete the qualified rules first, and then delete the
unqualified rule.
• You cannot delete an Operator ID if the operator has any checked-out rules. Before
you delete an Operator ID, the operator needs to sign in, and delete or check in all
rules in the personal ruleset.
• You cannot delete a concrete class that contains instances.
• You cannot delete a class, either concrete or abstract, if the system contains rules
with the same class name as the Applies To class. You receive a notification with a
list of the rules that you need to delete before you delete the class rule.
• You cannot delete a ruleset version rule that identifies a non-empty collection of
rules. First, you need to delete each of the rules in the version.
• You cannot delete a ruleset for which a ruleset version exists. Delete each version
first.

1. In the navigation pane of Dev Studio, click Records.

2. In the Records explorer, expand the category of the rule that you want to delete,
and then click its rule type.

For example:

If you want to delete an activity, expand the Technical category, and then
click Activity.

3. In the list of rule instances, click the rule that you want to delete.
4. Click Delete.
5. In the Delete dialog box, describe the reason for deleting the rule, and then click
Delete.
6. Optional: To undo your changes while you still have the rule open, click Restore.

©2023 Pegasystems Inc

 Pega Platform 8.8 204

What to do next:

Recover a specific version of a deleted rule. For more information, see

Recovering a deleted rule.

• Recovering a deleted rule

• Performing a private edit

• Copying a rule or data instance

Recovering a deleted rule

Facilitate application development by recovering one of the most recent versions of a
deleted rule. For example, if you accidentally delete a property, or delete a process rule
that seems irrelevant, but you later realize that you need the process to complete the
case life cycle.

Note: Recovering a deleted rule is a different operation than restoring a rule

immediately after deleting it. By recovering a rule, you can roll back the rule to
a specific version.

1. In the header of Dev Studio, click Configure > Application > Development >
Recent Actions.
2. Click View Deleted Rules.
3. Filter the relevant columns to narrow the results.

For example:

Filter the Type column to find removed activities, as shown in the following
figure:

©2023 Pegasystems Inc

 Pega Platform 8.8 205

List of deleted activities

4. Find the rule that you want to recover, and then click the value in the Rule name
column to open the rule.
5. Click Restore.
6. Click Save.

• Restoring the earlier state of a rule

Exploring rules in your application

To ensure that your application includes all the features that your business process
requires, explore rules that define these features. By exploring rules before you define
new elements of your app, you can also avoid duplicating resources, and as a result,
save time and development costs.

• Finding rules by type

• Finding rules by class

• Finding rules by name

• Finding rules by dependency

• Rule versions review and comparison

©2023 Pegasystems Inc

 Pega Platform 8.8 206

• Comparing rules by system

• Bookmarking a rule

• Searching for a rule

• Reporting on rules

• Viewing rule history

• Viewing rule versions

• Viewing the generated Java of a rule

• Viewing the XML of a rule

• Replacing a string in rulesets

• Finding deprecated rules in sections

Finding rules by type

You can use the Records Explorer to find all instances of a specific class, or rule type. By
using the Records Explorer instead of searching, you can quickly find a rule when you
know its type but do not know its name.

1. In the navigation panel of Dev Studio, click Records.

2. Expand the rule categories to browse the different rule types.
3. Click a rule type to display the instances of it that are defined in your application.
4. Review, sort, or filter the results to find your rule.
5. Click the rule to open it.

Finding rules by class

You can use the Application Explorer to find rules that share the same class. By using
the Application Explorer instead of searching, you can quickly find rules that are in your
application or inherited by your application, without having to know their names.

©2023 Pegasystems Inc

 Pega Platform 8.8 207

1. In the navigation panel of Dev Studio, click App.

2. Optional: To find rules in a specific built-on application, change the scope of the
Application Explorer.
a. Click applications.
b. Select the check box next to an application name.
c. Click Apply.
3. On the Classes tab, type one or more characters to display a list of matching class
names.
4. Click a class name to browse its rules and class structure.

Tip: To reset the Application Explorer to display rules in your team, clear
the class name.

5. Optional: To bookmark this class, hover on the class name, and then click the Pin
icon.
6. Expand subclasses and rule types, until you find the rule of interest.
7. Click the rule to open it.

• Understanding class hierarchy and inheritance

• Finding the class of a rule

Finding rules by name

To find sibling rules, which are rules with the same name (key parts) but different
rulesets or versions, do the following..

1. Open the rule form.

2. Select Actions > View Siblings to search the entire PegaRULES database for rules
that share a second key part with the currently displayed rule. The results are
displayed in a new window.

©2023 Pegasystems Inc

 Pega Platform 8.8 208

What to do next:

The Sibling rules window shows all the rules that share the same second key part
as the current rule. Not all of these are true siblings. This display is most useful
for rule types with two key parts that have an Applies To class as the first key
part.

The window might include rules in rulesets you cannot access, rules that are
unavailable, and circumstanced.

Rows in the display correspond to Applies To values. Numbers in brackets show

how many distinct rules (counting siblings, versions, circumstances, and so on)
are in each class.

Columns identify rulesets and versions. Each cell that contains an icon indicates
that a rule of that name and Applies To class exists, with an icon describing the
rule availability.

You can do any of the following actions:

• Click the Circumstanced link, which appears for a rule with circumstance
verions, to display the circumstance property and value.
• Select a value in the Applies To field to change its value and click Get
Related Rules to view rules with the same second key part in other classes.
• Click Legend to view a legend for this window.
• Click Details to display information about the sibling rules.

Finding rules by dependency

Save development time and find rules by dependency with the Referencing Rules tool.
Instead of conducting a full-content search, you can quickly locate a rule in context by
tracing the relationship between the rules in your application.

©2023 Pegasystems Inc

 Pega Platform 8.8 209

For example, before you remove steps from a data transform, you can use the
Referencing Rules tool to find the rules that the removal affects.

Note: Some rules do not support the Referencing Rules tool, because their
references are determined at run time.

1. Open a rule whose dependencies you want to check.

2. Click Actions > View references.
3. Review the list of rules in the Referencing Rules and Referenced Rules tabs to
understand the relationships between the rules.
4. Optional: To open any of the rules listed in the tabs in their own, new tab, click
the Edit icon.
5. Optional: To filter the results, on the Referencing Rules tab, click the Settings
icon, and then choose any of the following options:
• To narrow the search results to the rules used only in the application, in the
Rule Sets list, select Application Only.
• To include rules with the same name in the same class path, select the Show
overrides check box.
• To include other versions of the rule, select the Show Versions and
Circumstances check box.

Finding rules by custom field

The Find Rules by Custom Field wizard helps you generate a tailored report of rules in
the system with custom fields defined.

Note: Only Decision rules are supported by this wizard by default. You can
include additional rule types in search results by overriding the standard list
view rule Rule-Obj-Class.getCategorizedRules.

©2023 Pegasystems Inc

 Pega Platform 8.8 210

1. In the header of Dev Studio, click Configure > Case Management > Tools > Find
Rules By Custom Field.
2. Filter the search results based on the value of a custom field.
3. Choose which property values to include in the report that the wizard generates.
4. Review the report.

Selecting a rule in the Find Rules by Custom Field wizard

Select the rules you want to include in the search by performing one of the following
actions.

• Select the check box next to an individual rule type to include it in search results.
• Select the check box next to a rule category to include a group of rule types in
search results.

Next: Setting filters

• Finding rules by custom field

Find Rules by Custom Field Wizard - Step 2

Setting filters in the Find Rules by Custom Field wizard

Before you begin:

Enter criteria in this step to filter results based on the value of a custom field. For
example, you can find all rules with an applies to class name that starts with
Rule-Obj or a ruleset name that contains the string customer.

1. Select a label from the Field menu of the custom field to evaluate. This list is
populated by values in the pr_index_customfields database table. If you do not
see a custom field in the list, it must be exposed as a column.

©2023 Pegasystems Inc

 Pega Platform 8.8 211

2. Select a comparison technique from the Condition menu.

3. Enter a string in the Value field to compare it with the value of the custom field
selected in the Field menu.
4. Add rows to define additional criteria or delete rows to remove them.
5. In the Filter Logic (Advanced) section, specify the search criteria order of
operations. Each row in the Filter by Custom Fields section is labeled by a letter.
Enter a logical string using these letters, parentheses, and keywords AND, OR,
NOT; for example, (A AND B) OR C. If no logical string is specified, the system uses
AND to join all search criteria together.

What to do next:

Previous: Selecting a rule Next: Selecting fields

• Optimizing database properties

Find Rules by Custom Field Wizard - Step 3

Selecting fields in the Find Rules by Custom Field wizard

Include additional properties in the generated report. The selections you make here
only augment the returned results; they do not filter them.

Select the check box next to the property names to include as columns in the final
report. You must select at least one property. As a best practice, include the Rule Type
property to help organize results.

Previous: Setting filters Next: Viewing the report

©2023 Pegasystems Inc

 Pega Platform 8.8 212

Find Rules by Custom Field Wizard - Step 4

Viewing the report in the Find Rules by Custom Field wizard

Review the list of rules matching the custom field search criteria. You can expand the
report to look at individual items or view the full results offline in Excel.

Results are limited to 1000. Use more specific filter criteria to help isolate results.

Previous: Selecting fields

Rule versions review and comparison

Inspecting and comparing rule versions helps you resolve merge conflicts, review and
debug code, and audit changes that a developer made while the rule was checked
out.For example, you can compare the rule that you currently work on with previously
checked out versions of the rule, branched versions, or the same rule in other ruleset
versions.

Depending on your needs, you can inspect and compare rules in Pega Platform in the
following ways:

Viewing changes to a specific rule on the History tab of the rule

View changes to a rule by reviewing different versions of the rule.

For more information, see Viewing changes to a specific rule.

Viewing versions of a rule on the Actions menu on a rule form

View differences between the current rule and a selected version and modify your
version of the rule.

For more information, see Comparing rule versions.

©2023 Pegasystems Inc

 Pega Platform 8.8 213

Comparing rules and rule versions with the Compare Rules tool
Compare two different rules or two versions of a rule. The tool displays results in
a user- friendly, color-coded way. You also can use the tool to export the results to
a Microsoft Excel spreadsheet.
You can compare rules of the following types:

• Activity
• Data Transform
• Function
• Validate
• Other technical rules that are text, such as the text files, JSP, and HTML rules.

For more information, see Comparing rules and rule versions with the Compare
Rules tool.

Viewing changes to a specific rule

Get quick and full insight into the changes to a rule by reviewing different versions of
the rule on the History tab of the rule.

1. Open the rule that you want to compare.

For more information, see Exploring rules in your application.

2. On the rule form, click the History tab.

3. In the History details section, click View full history.
4. In the new window, click History for All Versions to display all versions of the rule.
5. In the list that appears, select the Compare check box for each version of the rule
that you want to compare.

Note: If the current rule is checked out, the Compare With Checked Out
button appears.

©2023 Pegasystems Inc

 Pega Platform 8.8 214

6. If the current rule is checked out, to compare a rule version with the checked out
version, select a version, and then click Compare With Checked Out.
7. In the Differences Found report, select a rule to view the differences between the
rule versions.

Comparing rule versions

Compare rule versions to resolve merge conflicts, debug code, and audit changes that
application developers made during rule check out. You can compare a rule with
versions of the rule from before the rule check out, with the branched versions, or with
the same rule in other ruleset versions.

1. In the navigation pane of Dev Studio, click Records.

2. Expand the category that stores your rule, and then select a subcategory.

For example:

Click Process, and then click Service Level Agreement.

3. In the list of rules, click the name of the rule for which you want to run the
comparison.
4. In the header of the rule form, click Actions.
5. Click View versions, and then select the version of the rule that you want to
compare with the current rule.
6. View the list of differences between the current rule and the compared version.
For the current rule, each list entry shows:
• The type of changes.
• The name of the changed page or property.
• For modifications, the former and current values.
7. If you review rules properties that store code, use a compare tool that provides a
detailed view of changes between versions.
a. Click Compare text on a difference that you want to examine to view all the
changes between versions.

©2023 Pegasystems Inc

 Pega Platform 8.8 215

Tip: You can move to a specific change by clicking the drop-down

arrow, and navigate between multiple changes by clicking the
arrows.

b. Optional: To make changes to the current version of the file, you can edit,
add, or remove text.
c. Optional: To replace a change in the currently edited rule with the version of
the rule that you use in comparison, click the Revert chunk icon next to the
change.
d. Optional: To replace all your changes with the version of the rule that you
are comparing to, click the Undo all changes icon.
e. After you review the changes, click Done.
8. Click the entry on the list to highlight the tab and element with the change on the
current rule form.
9. Optional: To see additional information about page and property changes,
expand a list entry.
10. If you make changes to the current rule in this view, click Save changes to
compare your revisions.

Note: If the Save changes option is not visible, it means that you do not
have permission to make changes to the rule. To make and save changes
to the rule, exit the Compare view and either check out the rule or save it
into a branch.

11. Optional: To compare the current rule with another version, select the other
version from the list in the Compare Rule header. The view is refreshed with the
revised change information.
12. Click Exit compare to return to the rule form.

©2023 Pegasystems Inc

 Pega Platform 8.8 216

Comparing rules and rule versions with the Compare Rules tool

Apply the Compare Rules tool to two different rules or two versions of the same rule to
identify and review changes between rules. The side-by-side comparison lets you
quickly find the additions, deletions, or value changes that have occurred between two
versions of a rule.

1. In the header of Dev Studio, click Configure > System > Refactor > Rules.
2. Click Compare Rules.
3. In the Instance #1 section, specify the first rule by providing the following
information:
a. In the Rule Name field, enter the name of the rule that you want to compare.
b. In the Rule Type field, click the displayed rule type and select a value from
the list.
c. In the Applies To field, select the class that contains the rule.
d. In the RuleSet field, select the ruleset that contains the rule.
e. In the Version field, select the ruleset version that contains the rule.
f. Click Find.
4. In the list of rules that appears, mark the Select field of the first rule that you want
to compare.
5. In the Instance #2 section of the new panel, select the second rule to compare by
performing one of the following actions:
• If the second rule instance that you want to compare is in the list, to select it,
click the button beside the rule name.
• If the second rule instance that you want to compare is not in the list, in the
new panel, repeat actions from step 3, and then, in the list of rules that
appears, mark the Select field of the second rule that you want to compare.
6. Click Compare >> to generate the Differences Found report.
7. In a selected column of the report, click a row entry that has a change to display
the Comparison of rules form.
The form displays the first selected rule in the left column and the second rule in
the right column.

©2023 Pegasystems Inc

 Pega Platform 8.8 217

The differences are color-coded:

Yellow
The values have changed in the two selected instances.
Green
At least one property value in the second rule is not present in the first rule.
The first selected rule is presumed to be the source instance. Consequently,
the changes highlighted in green are considered additions.
Red
At least one property with values in the first rule is not present in the second
rule. The first selected rule is presumed to be the source instance.
Consequently, these changes are deletions.

If the screen displays code that includes more than one change, you can move
among changes by clicking the left and right arrow keys at the top of the screen.
You can also use the search field to locate a specific text string.

Browse the changes by using the scroll bars at the right of each column. Each
scroll bar controls both columns, which move together to maintain the
relationship between the material displayed from each rule instance.

8. Optional: To save the comparison results to a Microsoft Excel spreadsheet, click

Export to Excel.

Comparing rules by system

You can use the Rulebase Compare wizard to identify differences in the rules present
on two Pega Platform systems. For example, you can use the tool to confirm the
success of a product migration between systems, or to identify the changes needed to
synchronize two systems.

Starting the tool

Select Configure > System > Refactor > RuleSets > Rulebase Compare to start the
wizard. For instructions on the form, see Using the Rulebase Compare tool.

©2023 Pegasystems Inc

 Pega Platform 8.8 218

You specify the target system and the RuleSet or a Rule-Admin-Product rule to compare.
The same RuleSet or Rule-Admin-Product must be on both systems. The comparison
processing is performed on the system on which you are running the Rulebase
Compare wizard.

Using the Rulebase Compare wizard — Step 1: Enter System Info

Use this wizard form to specify the target system for the rule base comparison.

Complete the following fields to specify the system you want to compare to your
current system.

Field Description

Select a System If you previously saved a target server

definition, select it from the drop-down.

Host Name Target server host name.

Port The TCPI/IP port number for SOAP

connections on the target server. Often this
is port 80.

Context Root Target server context root name for the Pega
Platform application.

HTTPS? Select if the port requires an HTTPS (Secure

Socket Layer) connection.

Save Click to save this system specification for

future use. Saved specifications appear in
the Select a System drop-down the next time
you use this wizard.

Username Enter a valid operator ID for the target

server.

Password Enter the user password for the operator ID

you specified.

©2023 Pegasystems Inc

 Pega Platform 8.8 219

Field Description

Next >> Click to continue to the next step of the

wizard.

Cancel Click to exit the wizard.

Using the Rulebase Compare wizard — Step 2: Select Instances

Use this wizard form to specify the ruleset or product that defines the set of rules you
wish to compare.

Note: If you are comparing products, make sure both product rules you are
comparing include all the rulesets that you want to compare.

Field Description

Specify Collection Method Select the type of rule collection you want to
compare: RuleSet or Rule-Admin-
Product.

Select Rule Admin Product Parameters If you selected Rule-Admin-Product as

the Collection Method, complete the
following fields:

Name Select the product rule on the current system

that you want to compare with the target
system.

Version Select the version of that Rule Admin

Product that you want to compare.

Select RuleSet Parameters If you selected RuleSet as the Collection

Method, complete the following fields:

Click the insert row icon to add a row of

ruleset parameters. Add a row for each

©2023 Pegasystems Inc

 Pega Platform 8.8 220

Field Description

ruleset you want to include in the

comparison.

RuleSet Name Select the name of the ruleset on the current

system that you want to compare to the
target system. Choose a ruleset that is
present in both systems.

Minimum Version, Maximum Version Select the minimum and maximum ruleset
versions of the ruleset you have selected to
compare with the target system. The version
range must match ruleset versions on the
target system. If you do not specify a range,
all versions are assumed.

Using the Rulebase Compare wizard - Step 3: Display Summary

The Parameter Review form displays your target system specification and the rulesets
or product rule you have chosen to compare.

Review this information to make sure you are performing the comparison you intend
to.

Using the Rulebase Compare wizard — Step 4: Display Report

The Synchronization Report lists the rules, rulesets, and ruleset versions in which
differences were found between the source and target systems. For each rule the
wizard identifies the action to be performed on the target system to make it match the
source system.

Results

The wizard identifies the following types of actions:

©2023 Pegasystems Inc

 Pega Platform 8.8 221

• Add – Rules that appear on the source system but that are missing on the target
system. Add these rules to the target system to match the source system. The
system determines additions and deletions by comparing values of pzInsKey, the
permanent handle of a rule.

• Delete – Rules that are not on the source system but that are found on the
target system. Delete these rules from the target system to match the source
system.
• Update – Rules that have a different time stamp ( pxUpdateDateTime ) on the
source system than on the target system. The wizard only identifies a difference in
the update times between the systems for these rules; the report does not
indicate which is more recent. Compare these rules on the two systems to
determine whether you want to preserve the change in the most recently updated
rule or use the older rule without the change.

Do not assume that rules with the most recent pxUpdateDateTime values correspond to
the highest version. Rules in any version can be updated at any time.

Click Export to Excel to save this listing in a spreadsheet.

Bookmarking a rule
You can use favorites to bookmark a rule so that you can quickly find it later. You can
create favorites that are visible to your operator exclusively, another operator, or all
operators within a specified access group.

Before you begin:

• Make sure that the rule you are adding as a favorite is not a checkout.
• Make sure that you have opened the correct version of the rule to add as a
favorite.

For example, a rule can have a base version and 50 circumstanced versions,
one for each state in the United States. You can add the Vermont instance

©2023 Pegasystems Inc

 Pega Platform 8.8 222

as a favorite to Doug Smith and the California instance as a favorite to Belle

Cruise, respectively.

1. In the Actions menu of the rule form header, click Add to Favorites.
2. Enter text in the Label field that distinguishes this favorite from other delegated
rules.
The value you specify appears in the Favorite Explorer and the operator menu in
Dev Studio.
3. In the Add to drop-down list, indicate who can access this favorite:
• My Personal: Visible to your operator only.
• My Access Group: Visible to all operators in your current access group.
• Other Access Groups: Visible to operators in the access group you specify.
• Other User Personal: Visible to the specified operator ID only.
4. Select an option to indicate how the system finds this favorite:
• Open the highest version: Rule resolution is used to find and open the
delegated rule.
• Always open this version: The exact version used to create the favorite is
opened, even if other instances exist in a higher ruleset version or class.
These radio buttons appear when a rule supports multiple versions.
5. Click Submit.

What to do next:

While you can no longer delegate rules by using favorites, you can use the
pyCMDelegatedRules harness in the Case Manager portal to view rules that were
previously delegated using the Add to favorites action.

©2023 Pegasystems Inc

 Pega Platform 8.8 223

Searching for a rule

Dev Studio provides full-text search for non-deprecated rules, data objects and the help
system. You can search help system topics at any time. Searching for rules or data
depends on system-maintained index files.

To start a search perform one of the following actions:

• Enter one or more terms (keywords) into the search text field and press Enter.
• Leave the search text field empty and press Enter to see a list of rules recently
updated by your operator.
• Click the Tick icon next to the search text field to see a list of rules that are
checked out by your operator.

What to do next:

• Use the following drop-down lists to control how results are displayed:

Menu Option Result

Result type Rules Only return instances

of classes derived from
the Rule– base class.

Data Only return instances

of classes derived from
the Data– base class.

Rules and Data Return results for all

record types.

Help Topics Only return topics

available in the Pega
Platform Help System.

Search Type Name Evaluate the

pyRuleName property

©2023 Pegasystems Inc

 Pega Platform 8.8 224

Menu Option Result

for Rule– instances, the

pxInsName for Data–
instances, and Help
topic titles when
looking for a match.

All Content In addition to record

names and help topic
titles, evaluate record
data (XML) and bodies
of help topics when
looking for match.

Match Criteria Contains Return results based on

words that match any
part of for the entered
term(s), including in the
middle of words.

Starts With Return results based on

words that begin with
the entered term(s).

Exact Match Return results based on

words that exactly
match the entered
term(s).

Scope My Current Application Only evaluate records

in your current
application when
looking for a match.

All Applications Evaluate records in

your entire application

©2023 Pegasystems Inc

 Pega Platform 8.8 225

Menu Option Result

stack when looking for

a match.

Note:

By default, matches include both rules and data instances.

Changes to filtering options are remembered only for the duration

of the session.

The Search tool does not search work items.

Rule–, Data– and other matches are ranked by Elasticsearch’s

default relevancy ranking, based on factors such as the number of
times that the search term appears in the object.

• Perform advanced searches:

The search capability is implemented using robust, fault-tolerant

Elasticsearch technology for use in distributed environments. Elasticsearch
will detect and remove failed nodes in a cluster, automatically replicating
and reorganizing nodes as needed.

Note: To take advantage of Elasticsearch distributed architecture,

multiple nodes should be configured to host Elasticsearch index
files. See Full text search.

The search terms entered are converted into the appropriate Elasticsearch
query syntax based on the search method chosen. You can enter more
advanced Elasticsearch query syntax to perform complex searches.

©2023 Pegasystems Inc

 Pega Platform 8.8 226

The following general rules apply to searches:

◦ Elasticsearch uses the ( * ) asterisk as a wildcard to match zero or

more characters, and the ( ? ) question mark as a wildcard to match
any single character. The * character is automatically added before
and after search terms when you use the Starts With (term * ) or
Contains ( * term * ) search method , and you do not have to
manually enter them.

◦ To search for a rule based on its Applies To class and name, select the
All Content option for Search Type (since pyRuleName does not
contain the class name), and enter a search such as class-
name*rule-name or class-name . For example, to see the version
of the pyLabel property within the Work- class, search for Work-
*pyLabel .

◦ If you enter two or more words, they are treated by default as a single
phrase during search.

◦ Your search string may contain characters - _ % or @. Your search

string may contain a ! but escaped with a preceding \ character.
Searches with any of these characters are exact match only. Searches
involving other special characters such as ( [ { }]} ^ ~ * # : \ | are not
supported.

◦ When a search string is enclosed in quotes, the selected search

method is ignored, and an Exact Match is always performed using the
exact text within quotes.

◦ Use the special syntax property-name:value to search for

instances with a specific property value. Set the Search Type option to
Content for this type of search. Enter an exact property name,
including capitalization. The searched value cannot contain any
special characters. Instances whose value starts with the value

©2023 Pegasystems Inc

 Pega Platform 8.8 227

entered are matched. For example, pxObjClass:Rule-Obj-Flow

returns a list of all Rule-Obj-Flow and Rule-Obj-FlowAction rules.
◦ You can enter more advanced Elasticsearch queries. For information
about the Elasticsearch query syntax, go to the Elasticsearch website
at elastic.co.

When entering advanced syntax, select Exact Match as the Search

Method. For example, you can use the Boolean operators AND , OR ,
and NOT to search for combinations of multiple terms and phrases.
Capitalize the Boolean operators to distinguish them from the terms
or phrases being combined. You can use parentheses to group
conditions. See the examples below.

Entered text Search method Syntax sent to Match

Elasticsearch returned if

abc Exact Match abc Exact word abc

exists in
searched text.

abc Starts With abc* One or more

words beginning
with abc exist
in searched text.

abc Contains *abc* One or more

words
containing abc
exist in searched
text.

abc def Exact Match abc def Exact phrase

abc def exists
in searched text.

©2023 Pegasystems Inc

 Pega Platform 8.8 228

Entered text Search method Syntax sent to Match

Elasticsearch returned if

abc def Starts With abc def* One or more

phrases starting
with the exact
word abc
followed by a
word starting
with def exists
in searched text.

abc def Contains *abc def* The string abc

def exists
anywhere in
searched text.

“abc:01-01-0 Any abc:01-01-01 Exact word

1” abc:01-01-01
exists in
searched text.

abc\:def Exact Match abc\:def Exact word

abc:01-01-01
exists in
searched text.

abc\:def Starts With abc\:def* One or more

words beginning
with abc:def
exist in searched
text.

abc\:def Contains *abc\:def* One or more

words
containing

©2023 Pegasystems Inc

 Pega Platform 8.8 229

Entered text Search method Syntax sent to Match

Elasticsearch returned if

abc:def exists
in searched text.

abc OR def Exact Match abc OR def Either the exact

word abc or
the exact word
def exists in
searched text.

abc* OR Exact Match abc* OR Either one or

*def* *def* more words
beginning with
abc or one or
more words
containing def
exists in
searched text.

abc AND def Exact Match abc AND def Both the exact
word abc and
the exact word
def exists in
searched text.

abc AND def Exact Match abc* AND Both one or

def* more words
beginning with
abc and one or
more words
beginning with
def exists in
searched text.

©2023 Pegasystems Inc

 Pega Platform 8.8 230

Entered text Search method Syntax sent to Match

Elasticsearch returned if

(+abc* Any (+abc* One or more

*def*) NOT *def*) NOT words starting
ghi* ghi* with abc exists
in searched text,
the string def
may also exist
anywhere within
the searched
text, and no
words starting
with ghi exist
in the searched
text.

Reporting on rules
You can report on rules of more than one type and rules that are checked out. For
reporting purposes, searching all instances of the classes derived from the Rule- base
class, or even all instances of the Rule-Service- class, can impact performance. To
provide more efficient reporting, you can create report definitions that query the
database view that corresponds to a particular class.

• To report on rules of more than one type, create a report definition rule with Data-
Rule-Summary as the Apply to class. The properties that you use for selection
criteria must be stored as exposed columns of the PegaRULES database view that
corresponds to the Data-Rule-Summary class.
• To report on rules that are checked out, create a report definition rule with Data-
Rule-Locking as the Apply to class.

• Viewing and running inventory reports

©2023 Pegasystems Inc

 Pega Platform 8.8 231

Viewing the heat map

You can view a heat map that shows in the number of rules in each category, broken
down by rule type. The size of each box reflects the number of rules of a single rule
type. Complete the following steps.

1. In Dev Studio, click Configure > Application > Inventory > Heat Map.
2. In the Shaded by list, select an option to graphically shade the heat map by
number of recently updated rules, number of warnings, or number of rules
checked out per category. The darker the shade, the higher the number of the
filtered type that is found in that rule type.
3. Click the Filter button to add or remove rulesets and rule categories from the heat
map.
4. Left-click a rule type on the heat map top open a report that displays all rules of
the selected type in the selected type in the application.
5. Right-click a rule type on the heat map to open a report that displays all rules of
the selected type in the application that match the filter selected for the recently
updated rules, the number of warnings, and the number of rules checked out per
category.

• Managing application inventory

Viewing and running inventory reports

Inventory reports are not associated with a specific application's work items,
assignments, or processing. You can run reports for which the Applies To key part is a
class derived from the System-, Data-, or Rule- base classes.

1. To view inventory reports, click Configure > Application > Inventory > Inventory
Reports.
2. Click the report name to open its rule form, and specify the appropriate
information.
3. To run the report, click Run from the Actions menu.

©2023 Pegasystems Inc

 Pega Platform 8.8 232

• Reporting on rules

Reviewing exposed properties

To enhance record selection operations for reporting, certain single value properties
are stored as exposed columns in an application. You can review which properties are
exposed in your appliction.

You can use exposed properties to search for archived cases.

1. Click Configure > Data Model > Classes & Properties > Database Class Mappings.
2. Locate your class in the Database Class Mappings table.
3. In your class's row, click the number in the Exposed/Mapped column to view
exposed properties for that class.

• Reporting

Viewing rule history

You can view the saved history of a rule to see when it was changed and by whom. You
can also compare the current version with a previous version or restore a previous
version of a rule for testing purposes, or if the current version is faulty.

1. Open a rule form, click the History tab, and then click View full history.
2. Click the Pencil icon next to a history record to see a previous version this rule
instance.
3. Optional: To make an older copy of the rule become the current copy, click
Restore on the rule form. For more information, see Restoring the earlier state of
a rule.
4. Optional: To compare rule versions, select any two versions of the rule from the
table and click Compare. For more information, see Comparing rule versions on
the History tab.
5. Click History For All Versions to see the history of all versions of this rule with the
same name, ruleset, and circumstance qualification, if any. To return to the

©2023 Pegasystems Inc

 Pega Platform 8.8 233

original display that show showing only the history of this open rule, click History
of Version NN-NN-NN.

Note: The History For All Versions button is not displayed for class rules
( Rule-Obj-Class rule type) and a few other rule types. Class rules have an
associated version field, but do not belong to a single specific ruleset
version.

Related tasks

• Viewing rule history

Viewing rule versions

View rule versions by selecting Actions > View versions. A dialog box appears and
displays the versions of the rule, their availability, and their circumstance. You can click
an item to open the rule form.

You cannot view versions on rules that are not versioned, such as applications, classes,
and rulesets.

Viewing the generated Java of a rule

After you save a rule form, you can view an approximation of the generated Java to be
created by a rule instance by selecting Actions > View Java.

You can view Java if you have the @baseclass.ToolbarFull privilege, and you can view Java
for certain rules, including activities, when rules, and stream rules.

Viewing the XML of a rule

If you have the @baseclass.ToolbarFull privilege, you can view the XML document that
comprises the form that displays a rule instance by selecting Actions > View XML.

©2023 Pegasystems Inc

 Pega Platform 8.8 234

You can view the XML document to assist in debugging so that you can identify the
property names and the handle for each property that is referenced in the form.

Note: If you have modified and saved the rule or data form, this information
might be out of date. To see updated information, close the form, open the
same rule or data type again, and select Actions > View XML again.

• Finding the class of a rule

Replacing a string in rulesets

Use the Search/Replace a String wizard to search for and replace a string wherever it
appears in rules in the entire PegaRULES database.

You can search and replace the string in:

• All rulesets in the system

• The rulesets included in your ruleset list.
• A single ruleset or set of selected rulesets

The wizard reports any locked rulesets or rules that are checked out before performing
the replacement, and any class names that might be affected. A list of qualifying rules
appears for your review before any rules are altered.

The wizard uses the full-text search to reduce search time and increase accuracy. If full-
text search for rules not enabled for your system, and you do not limit the scope of the
process to certain rulesets, the process can take many minutes to complete.

Use this powerful tool with care. Rules updated by this wizard are not automatically
revalidated and may become invalid as a result of string replacement. As a precaution,
export the rulesets in to a .zip archive or back up the entire PegaRULES database before
using this tool. The .zip archive can serve as a backup if the results of the wizard are not
satisfactory.

©2023 Pegasystems Inc

 Pega Platform 8.8 235

Select Configure > System > Refactor > Rules > Search/Replace a String to start the
tool.

In changing a string, the utility looks for the specified string anywhere in any value
within any rule within the search scope, and gives you the option to select the rules you
want to modify. To specify the string to replace for the selected rules, it will replace the
original string with the replacement string.

Strings are replaced only in rules, not in work items, assignments, attachments, or
other objects. If string replacement changes rules in subclasses of Work- or any of its
properties, the subsequent processing of those work items in those classes may
encounter problems.

Finding deprecated rules in sections

Find sections that use deprecated rules by using an application upgrade utility. Once
found, these legacy rules can be updated to newer rules.

Your application might contain sections that use legacy rules or images. Legacy rules
and images have been deprecated or upgraded with newer rules. Update or refactor
legacy rules to use the latest Platform rules. You can search for legacy rules by using
the Application Upgrade Utilities.

Note: Images are found using index references and the results are compared
using rules names. This means that even after you fix an image in a section,
the rule might still be listed in the report.

1. Click Configure > System > Release > Upgrade > Upgrade tools.
2. Click the List rules using legacy rules link.
3. From the list of rules, select a rule to open it. From here you can upgrade or
refactor the rule.

• Moving applications between systems

©2023 Pegasystems Inc

 Pega Platform 8.8 236

• Importing the legacy ruleset from the Resource Kit

©2023 Pegasystems Inc