Senior System Architect

7.4
Student Guide
 © 2018
Pegasystems Inc., Cambridge, MA
All rights reserved.

Trademarks

For Pegasystems Inc. trademarks and registered trademarks, all rights reserved. All other trademarks or service marks are property of
their respective holders.

For information about the third-party software that is delivered with the product, refer to the third-party license file on your
installation media that is specific to your release.

Notices

This publication describes and/or represents products and services of Pegasystems Inc. It may contain trade secrets and proprietary
information that are protected by various federal, state, and international laws, and distributed under licenses restricting their use,
copying, modification, distribution, or transmittal in any form without prior written authorization of Pegasystems Inc.

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

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

Although Pegasystems Inc. strives for accuracy in its publications, any publication may contain inaccuracies or typographical errors, as
well as technical inaccuracies. Pegasystems Inc. shall not be liable for technical or editorial errors or omissions contained herein.
Pegasystems Inc. may make improvements and/or changes to the publication at any time without notice.

Any references in this publication to non-Pegasystems websites are provided for convenience only and do not serve as an
endorsement of these websites. The materials at these websites are not part of the material for Pegasystems products, and use of
those websites is at your own risk.

Information concerning non-Pegasystems products was obtained from the suppliers of those products, their publications, or other
publicly available sources. Address questions about non-Pegasystems products to the suppliers of those products.

This publication may contain examples used in daily business operations that include the names of people, companies, products, and
other third-party publications. Such examples are fictitious and any similarity to the names or other data used by an actual business
enterprise or individual is coincidental.

This document is the property of:

Pegasystems Inc.
One Rogers Street
Cambridge, MA 02142-1209
USA
Phone: 617-374-9600
Fax: (617) 374-9620
www.pega.com

DOCUMENT: Senior System Architect Student Guide

SOFTWARE VERSION: Pega 7.4
UPDATED: 08 2018
CONTENTS

COURSE INTRODUCTION 1
Before you begin 2
Senior System Architect overview 2

APPLICATION DESIGN 4
Creating a Pega application 5
Introduction to creating a Pega Platform application 5
Enterprise Class Structure 6
Creating a new application version 9
Introduction to creating a new application version 9
Application versioning 10
How to create a new application version 13
Configuring application rulesets 15
Introduction to configuring application rulesets 15
Rulesets 16
Ruleset validation 18
The ruleset list 23
How to manage changes to rules in a ruleset 25
Branching rulesets for parallel development 28
Introduction to branching rulesets for parallel development 28
Parallel development 29
How to develop in parallel by branching rulesets 31
How to merge changes from a branched ruleset 35
Rule resolution 38
Introduction to rule resolution 38
Rule resolution 39
How the rule resolution process works 41
How the rules cache is populated 45
How to influence rule resolution through rule availability 58
Parameterizing rules for reuse 61
Introduction to parameterizing rules for reuse 61
Parameters 62
How to make rules reusable with parameters 65
How to pass a parameter value to a rule 67

CASE DESIGN 69
Creating temporary cases 70
Introduction to Creating Temporary Cases 70
Temporary Cases 71
Configuring temporary case processing 73
Searching for duplicate cases 77
Introduction to searching for duplicate cases 77
Duplicate cases 78
How to identify duplicate cases 80

DATA MODEL DESIGN 84

i
©2018 Pegasystems
Configuring a localizable list of values 85
Introduction to configuring a localized list of data values 85
Field values 86
How to configure field values 88
Configuring data access patterns 90
Introduction to configuring data access patterns 90
Data access patterns 91
How to configure the reference pattern 94
How to configure the SoR pattern by referencing a data page from a property 95
How to configure the snapshot pattern by copying data from a data page 97
How to configure the keyed access pattern using keyed data pages 99
How to configure the alias pattern using reference properties 102

PROCESS DESIGN 104

Creating organization records 105
Introduction to creating organization records 105
Organization records 106
Work groups 108
How to update an organizational structure 111
Creating a work group and a workbasket 116
How to customize reusable processes with Dynamic Class Referencing 119
Configuring a cascading approval process 124
Introduction to configuring a cascading approval process 124
Cascading approval 125
How to configure cascading approval 127
Configuring cascading approval 130
Prioritizing user assignments 132
Introduction to prioritizing user assignments 132
Assignment models: user- and system-selected 133
How to manage assignment selection 135
Delegating rules to business users 139
Introduction to delegating rules to business users 139
Rule delegation 140
How to delegate rules to business users 143
Delegating a rule to business users 146
Configuring parallel processing 149
Introduction to configuring parallel processing 149
Parallel processing in Pega applications 150
How to configure parallel processing 153
Case locking 157
How to configure case locking 160
Improving the user experience with screen flows 162
Introduction to improving the user experience with screen flows 162
Screen flows 163
How to configure a screen flow 165
Configuring a screen flow 169
Adding attachments 171
Introduction to adding attachments 171
Attachments 172

ii
©2018 Pegasystems
 How to configure a case to accept attachments 174
How to configure attachment access 176
Configuring flow action pre- and post-processing 178
Introduction to configuring flow action pre- and post-processing 178
Pre- and post-processing in flow actions 179
How to configure pre- and post-processing for flow actions 181
Circumstancing rules on multiple variables 183
Introduction to circumstancing rules on multiple variables 183
How to circumstance a record with multiple variables 184
How circumstancing affects rule resolution 187
How to override circumstanced rule 188

UI DESIGN 191
Customizing a user portal 192
Introduction to customizing a user portal 192
User portals 193
Harnesses 194
How to customize a user portal 196
Changing the logo image in a user portal 199
Designing a mobile-ready application 200
Introduction to designing a mobile-ready application 200
Mobile design approaches 201
Mobile-friendly controls 204
Customizing the look and feel of an application 207
Introduction to customizing the look and feel of an application 207
Styling an application with skins 208
How to customize application appearance with skins 211
Controlling application appearance with a skin 214

REPORT DESIGN 219

Creating reports that combine data from multiple tables 220
Introduction to creating reports that combine data from multiple classes 220
Data storage in Pega 221
Class mappings and database tables 222
How to combine classes using joins and associations 226
Creating class joins and associations in reports 229
How to combine data from different classes using a subreport 232

DATA MANAGEMENT 235

Exposing an application with a service 236
Introduction to exposing an application with a service 236
How to expose an application as a service 237
Creating a SOAP service using the Service Wizard 241
How to configure exception processing 247
Reading and writing data to the database 249
Introduction to reading and writing data to a database 249
The PegaRULES database 250
External databases 251
Obj- methods 253

iii
©2018 Pegasystems
 How to connect to an external database 255
How to use symbolic indexes to reference lists 259
How to execute SQL using Connect SQL rules 261
Connecting to an external database 264
Simulating integration data 267
Introduction to simulating integration data 267
Integration simulation 268
How to simulate an integration 270
Simulating connector data 273
Addressing integration errors in connectors 275
Introduction to addressing integration errors in connectors 275
Error handling in connectors 276
How to configure error detection 277
Configuring error detection for integration 279
How to address errors returned by a connector 282
Managing integration settings 286
Introduction to managing integration settings 286
Global resource settings 287
How to configure a global resource setting for a connector endpoint 289

APPLICATION DEBUGGING 293

Reviewing log files 294
Introduction to reviewing log files 294
Log files 295
How to access system log files in Pega 297
How to use the PegaRULES Log Analyzer (PLA) 299
Monitoring logs remotely 301
Analyzing application performance 303
Introduction to analyzing application performance 303
Performance testing 304
How to analyze performance with the Performance Analyzer 305
How to analyze application performance with Database Trace 307
How to analyze application performance with Performance Profiler 309

APPLICATION ADMINISTRATION 311

Securing an application 312
Introduction to securing an application 312
Access control 313
Access control record types 316
How to manage access control 320
How to add roles to an access control model 324
How to manage access to individual rules 326
How to manage user access with access groups 329
How to secure workbaskets and attachments 333
Creating agents for background processing 335
Introduction to creating agents for background processing 335
Standard agents 336
How to perform background processing with an agent 337
How to troubleshoot issues with agents 340

iv
©2018 Pegasystems
Migrating an application 343
Introduction to migrating an application 343
Product rule 344
How to create an application archive file 345
How to associate data instances with rulesets 346
How to configure a product rule 347
Exporting an application using the Application Packaging wizard 352
Importing an application archive 359

COURSE SUMMARY 361

Next steps for Senior System Architects 362
Senior System Architect summary 362

v
©2018 Pegasystems
COURSE INTRODUCTION

1
©2018 Pegasystems
 Before you begin
Senior System Architect overview
The Senior System Architect course is an advanced course designed to help application developers
further their knowledge of application development on Pega Platform. The lessons in this course focus
on tasks a senior system architect performs to develop a Pega application.
The exercises in this course are based on Pega Platform 7.3. You may notice slight navigation changes
in the Pega Platform in subsequent releases. The provided instructions and screen captures can be
easily applied to the newer versions. In other cases, supplemental material has been added to the
course content. Look for references to the current version.
Exercises in this course apply to: Pega Platform 7.3, Pega Platform 7.4.
Pega recommends that students complete System Architect Essentials 7.3 prior to starting this course.

Objectives
After completing this course, you should be able to:
l Identify the tasks and responsibilities of the Senior System Architect on a Pega Implementation
l Create and extend a Pega application
l Manage rules and rulesets
l Leverage the Enterprise Class Structure (ECS) to promote rule reuse between case types and
applications
l Configure roles, access groups, and privileges
l Manage data access within an application
l Create wizards to configure a sequence of assignments
l Design applications for multiple device types and screen sizes, including mobile devices
l Manage integration settings

Intended audience
This advanced course is designed to help System Architects further their knowledge of Pega Platform
and improve their ability to implement Pega solutions in an efficient manner.

Prerequisites
To succeed in this course, students should have:

2
©2018 Pegasystems
l Some familiarity with application development concepts
l Completed the System Architect Essentials 7.3 course

3
©2018 Pegasystems
APPLICATION DESIGN

4
©2018 Pegasystems
 Creating a Pega application
Introduction to creating a Pega Platform
application
Developing new applications from the ground up can be an overwhelming task for any organization
and developer. Every application should adhere to an established set of organizational standards to
simplify maintenance, customization, and reuse.
The New Application wizard enables you to create new applications in a few minutes, while ensuring
you are following organizational best practices and standards.
After this lesson, you should be able to:
l Define the enterprise class structure (ECS)
l Differentiate between the Implementation layer and Framework layer
l Create an application with the New Application wizard

5
©2018 Pegasystems
Enterprise Class Structure
An enterprise can have a complex organization structure with many locations. The enterprise may sell
more than one product or service through multiple channels to different types of customers.
When you conduct business in different locations or countries, you need a way to manage the
regulations of each jurisdiction, and the cultural differences in each region. When you sell multiple
products through multiple channels, you need a way to manage the business rules for selling each
product in each channel separately. Also, when you sell to different types of customers, you need a way
to manage each customer's expectations and preferences.

With some application development platforms, you must create separate copies of the application for
each product, region, or channel. Or, you must create a single application that treats all business
transactions the same, regardless of the business context. The result is enterprise applications that do
not scale and are hard to maintain.
Pega's Situational Layer Cake allows you to organize your application using the same dimensions as
your business. The Situational Layer Cake makes reusing common policies and procedures easy while
allowing for differences between products, regions, channels, and customer segments.
The Situational Layer Cake is implemented in Pega 7 using a class hierarchy called an Enterprise Class
Structure (ECS).

The ECS enables you to organize your application using the same dimensions as your business. The
ECS makes reusing common policies and procedures easy while allowing for differences between
divisions and products. When you place a rule in an ECS layer, it may be shared across multiple
applications. As business operations change, existing layers of the ECS can be modified to address the
changes.

6
©2018 Pegasystems
Building an application on top of a well-designed class structure is vital for application scalability. A
well-designed class structure also enforces best practices around reuse and standardization as the
system expands to other lines of business.
KNOWLEDGE CHECK

State two advantages of organizing rules using an ECS.

Using an ECS helps you organize rules in a way that makes them scalable and encourages reuse.

Enterprise Class Structure layers

The ECS enables multiple Pega applications within the same system to coexist, and supports effective
reuse among the applications.

Note: For each release of Pega 7, the generated class structure reflects best practices available in that
release.

Pega Platform layer

The Pega 7 layer contains the built-in assets necessary for processing cases and other work in Pega
applications. This layer also contains assets used by Pega 7.

Organization layer
The Organization layer contains the assets used on an enterprise-wide basis. Such assets are rules
for enterprise-wide business logic such as standard properties, decision tables, and service level rules.
For example, a property that holds a customer's account number would be reused on an enterprise-
wide basis. As a result, the applications used across the enterprise can rely on the same account
number property without having to make copies of the property in every application.
The Organization layer also contains enterprise-wide data assets such as classes and rules for data
stored in the system, and classes and rules for access to data in external systems, via connectors. For

7
©2018 Pegasystems
example, access to an external customer database is an integration point that may be added to the
Organization layer.

Division layer
The Division layer contains the assets used on a division-wide basis. The division layer is the middle
level of the three-level organization hierarchy (Org-Div-FW) and is available for use in every application.
Assets in the Division layer may be applicable to a line of business, or for regions, brands, or
departments. For example, a line of business wants to reuse a service level rule that defines the
expected response time to a customer complaint in all of its applications. Placing the service level rule
in the Division layer helps ensure all applications have access to the service level rule without having
to create separate copies.
Note: The Division layer is an optional layer. When used, the Division layer is parallel to the Framework
layer.

Framework layer
The Framework layer contains the assets used to create generalized, reusable applications. A
framework application is then extended by specific implementations.
For example, a finance company provides auto loans. An auto loan framework is created that contains
all of the assets needed for the standard auto loan process. Each line of business may extend the basic
auto loan application to meet specific business needs. For example, the commercial business line
division's auto loan application needs to handle loan requests that are distinct from that of the
personal line division.

Implementation layer
The Implementation layer defines an implementation of a framework that is customized for a
specific division, or line of business. For example, the commercial business line's auto loan application
reuses assets from the commercial business line division layer and from the auto loan framework
layer. The personal line's auto loan application reuses assets from the personal line division layer and
the auto loan framework layer.
Note: While the assets in the Framework layer are designed for maximum reuse, the assets in the
Implementation layer are specific and cannot be reused elsewhere.
KNOWLEDGE CHECK

In which layer of the ECS do you organize assets used to create generalized applications?
The Framework layer

KNOWLEDGE CHECK

When used, the Division layer is parallel to the __________________ layer.

Framework

8
©2018 Pegasystems
 Creating a new application version
Introduction to creating a new application
version
Pega provides the ability to preserve a version of an application. You can edit application functionality
in a new version of the application without changing the initial version.
After this lesson, you should be able to:
l Identify the application components that versioning impacts
l Explain the role of versioning in application development
l Explain the purpose of ruleset skimming
l Create a new application version

9
©2018 Pegasystems
Application versioning
Pega provides two methods for creating new versions of an application. Each method preserves prior
application versions. Application versioning is a way to differentiate current and past application
configurations. Rule resolution can look through all the minor and patch versions for the current major
ruleset.
Application components include the application ruleset stack — this contains the rules and data types
used by the application. To version an application, you must version the application's rulesets.
The versioning methods are lock and roll and skimming. The act of using a version method begins a
release cycle. Every major version, minor version, and patch version represents a release cycle. Both
methods list the highest version, and offers to roll the ruleset to a still-higher version by default.
The person performing the lock and roll or skim must understand the application structure. A senior
system architect (SSA) or lead system architect (LSA) is able to understand application structures.
Your choice of method depends on the type of application change. Lock and roll is best for
incrementing patch versions. Skimming is better for minor and major versions.

Lock and roll

Small changes or patches are ideal for lock and roll. Application patches and minor updates usually
involve updating rules. When using lock and roll, you create a new empty ruleset version. To update
the configuration, you copy the necessary rules into the new ruleset version.
The rule in the higher ruleset version overrides the rule in the lower version. You specify the new
version number and whether to update the application record and access groups to reflect the ruleset
version.
Note: Minor and major versions require application record and access group updates. Patches usually
do not need the updates.
If you roll 01-01-01 to 02-03-01, Pega will start at 02-03-01 and look back to the previous minor version,
02-01-01, to find rules. As long as the rule is present in one of the versions, Pega can find it. If a rule is
only in 01-03-05, rule resolution will not find it because it is in a different major version.
This graphic illustrates how a system architect would version an application. The lock and roll wizard
creates an empty ruleset. The system architect adds the appropriate rules to configure the new
version.

10
©2018 Pegasystems
In the previous example, an SSA ran lock and roll to create an empty 01-01-02 version. Then, a system
architect updated rule A in this version. When a user runs the application, they use the updated rule A
and rules B and C from the 01-01-01 ruleset.
Then, an SSA ran lock and roll to create the 01-01-03 version. A system architect copied rules B and C to
this version to update them. Now, when a user runs the application, they use the rule B and C from the
01-01-03 version and rule A from the 01-01-02 version. The copies of A, B, and C in 01-01-01 are all
overridden.
Finally, the SSA ran lock and roll to create 01-01-04. A system architect copied rule B to this version to
update that rule again. So, when a user runs the application now, they use rule B from the 01-01-04
version, rule C from the 01-01-03 version, and rule A from the 01-01-02 version. The copies of A, B, and
C in 01-01-01 are all overridden.
KNOWLEDGE CHECK

In lock and roll, what occurs after you use the wizard to create a new, empty ruleset?
A system architect copies the required rules into the empty ruleset to create the new application
version.

Skimming
Skimming is the process of saving the highest version of a rule into a new, higher ruleset version.
Skimming applies mainly to resolved rules. Skimming is useful when rule changes follow a logical
sequence. The two types of skims are minor and major. The skim types correspond with the update
types (major or minor/patch).
During a minor skim, rules are stored in a higher minor version, and during a major skim, rules are
stored in a higher major version.
A rule's availability status determines if the rule is carried forward. This table defines the rules that are
carried forward during a skim.

Rule Availability Status Carried forward?

Yes Yes
Blocked Yes
Final Yes
Withdrawn No - major update; Yes - minor update
No (not available) No

Blocked rules are carried forward because a blocked rule can block rules in other rulesets. You should
maintain blocking relationships.
The key to skimming is you can start at a major version and skim all minor and patch numbers into a
new version, or you can start at some minor version and work up from there.

11
©2018 Pegasystems
Pega provides a skimming wizard. For each rule instance in a specified ruleset, the wizard identifies
the highest-numbered version and creates a copy with the number you specify.
For more information on the ruleset wizard, view the Help topic About the Ruleset Maintenance wizard.
KNOWLEDGE CHECK

Why would you use skimming instead of lock and roll when versioning an application?
Skimming is the process of saving the highest version of a rule into a new, higher ruleset version.
Skimming streamlines application versions where rule changes follow a logical sequence.

Note: In the exercise, you version a patch update using lock and roll and create a new version of the
application.

12
©2018 Pegasystems
How to create a new application version
You determine the method to use to create a new application version. Your choice is based on the type
of application change. Small bug fixes and incremental application enhancement patches are ideal for
lock and roll. Skimming streamlines applications versions where rule changes follow a logical
progression.
Preprocess best practice recommends confirming the rules for the new version are checked in. You can
run a search for checked out rules from the Checked Out Rules page. An additional best practice is
locking all but the highest ruleset versions.

Lock and roll

Within lock and roll, you have three choices for updating the application rule: no change, edit the
current version, and create a new version.
You use Do not update my application when you update the patch version number of a ruleset
without updating the application ruleset list. By default, the application rule only lists the major and
minor version numbers for a ruleset, so incrementing the patch version number does not require a
change to the application rule.
You use Update my Application to include the new Ruleset Versions when you are rolling out an
application and updating the minor version or when the application rule lists the ruleset patch version
number. You may enter a new application description. The default application description is current. If
current application is locked, enter the application password.
You use Create a new version of my application when you want to lock and roll the version and
create a new application rule. You may enter a new application version, if different than the default
one increment higher. You may enter a new application description. The default application
description is current. If current application is locked, enter the application password.
You can also use Create a new version of my application to allow people access to more than one
version of the application (for example, during a phased roll-out or a test period).
You must select the appropriate ruleset versions for the lock and roll before proceeding. Most
selections will be the most recent version. However, an earlier version of a ruleset might be
appropriate. Application requirements dictate this decision.
You can view the rulesets in the current application version on the Ruleset Stack page. You can select
the appropriate ruleset versions, enter the ruleset passwords, and select the update option in the Lock
& Roll window.
KNOWLEDGE CHECK

When using lock and roll, what is the purpose of selecting the new version option?
You use create a new version when you want to lock and roll the version and create a new application
rule. You can also create a new application version when you want to have people access more than
one version of the application (for example, a phased roll-out or a test period).

13
©2018 Pegasystems
Skimming
In Designer Studio, navigate to the Refactor > RuleSets page to access the link to the Skim a RuleSet
page. Indicate whether the update is to be a major version (NN-01-01) or a minor version (NN-MM-01),
the ruleset(s) to skim, and the version number to be created. Click Skim to begin the process.
The system creates a new ruleset version and begins copying rules. A status area shows progress and
the results of the skim. The actual duration of the skim could be several minutes.
Tip: If errors occur, select the Total Number of Errors link in the lower right corner of the display
form to view error messages. The error list is difficult to access after the results form closes. Print the
list if you wish to research and address the errors after closing the form.
You must update application rules, the Requires RuleSets and Versions prerequisites array in RuleSet
version rules, and access groups to reference the new major version after the skim completes. Log out
and log in to access the new version.
Notes: Skimming only copies the rules in the major version you select. For example, if you skim 02-ZZ-
ZZ into 03-01-01, rules in version 01-ZZ-ZZ are ignored.

You must have the zipMoveSkim privilege to perform the skim. Pega provides a default role for system
architects which includes zipMoveSkim. SysAdm4 is the default system role for system architects.
SysAdm4 includes the zipMoveSkim privilege. When an application is in production, the SysAdm4 role
becomes the Administrator role.
For more information on skimming, view the Help topic Skim to create a higher version.
KNOWLEDGE CHECK

What tasks must you perform after the skim is complete?

Update the application rules, the Requires RuleSets and Versions prerequisites array in RuleSet
version rules, and the access groups to reference the new major or minor version.

14
©2018 Pegasystems
 Configuring application rulesets
Introduction to configuring application
rulesets
In this lesson you learn how to configure an application ruleset to package for distribution. You also
learn about the impact the configuration has during development and runtime.
After this lesson, you should be able to:
l Describe the purpose of a ruleset
l Describe the organization of rulesets in an application
l Compare the ruleset validation modes
l Identify how the ruleset list is built
l Add and remove application rulesets

15
©2018 Pegasystems
Rulesets
Rules are the building blocks of a Pega application. The rule type determines the type of behavior
modeled by the rule. In Pega, every instance of every rule type belongs to a ruleset. A ruleset is a
container or an organizational construct used to identify, store, and manage a set of rules. The primary
function of a ruleset is to group rules together for distribution. Understanding the relationship
between an application and rulesets is essential in order to understand development and run-time
behavior.
Each ruleset has versions. See the Help topic About ruleset versions for a primer on ruleset versioning.

Application rulesets
An application contains a set of rulesets. The New Application wizard creates the initial application
rulesets. When the application is generated, the created rulesets include two rulesets for the
application itself and two organizational rulesets. In the following example, HRApps and HRAppsInt
contain application configuration. The two organizational rulesets — in this example, TGB and TGBInt —
contain reusable organizational assets, such as data structures.
Note: The rulesets ending in Int are used for rules related to integration.
Add additional rulesets for reusable functionality that you might want to migrate to other applications.
For example, the integration wizards create separate rulesets for each integration. The CreditCheck
ruleset holds the integration assets for a connector used to perform a background check.

16
©2018 Pegasystems
Production rulesets
Production rulesets have at least one unlocked ruleset version in the production environment.
Production rulesets include rules that are updated in the production environment. The most common
use of production rulesets is for delegated rules. However, production rulesets can be used for any use
case requiring rules to be updated in a production environment.
Production rulesets are configured in the Advanced tab on the application record. In addition, the
production ruleset needs to be specified in the access group.

KNOWLEDGE CHECK

The default initial application created by the New Application wizard contains a set of
ruleset for the application code and __________ assets.
organizational

17
©2018 Pegasystems
Ruleset validation
Ruleset validation is performed every time a rule is saved. It guarantees that referenced rules are
available on the target system when the ruleset is promoted.
Ruleset validation does not affect rule resolution at run time, but is only applied at design time.
There are two options for the validation mode:
l Application Validation
l Ruleset Validation
The selected validation mode applies to all versions of the ruleset.
The New Application wizard creates rulesets that are set to both Application Validation (AV) and
Ruleset Validation (RV) modes. The rulesets containing the application rules are AV mode to reduce the
difference between design and run time.
Conversely, the organizational rulesets created by the New Application wizard are RV mode. RV
ensures strict validation on prerequisite rulesets when migrated.

Application validation mode

If the AV mode is used, rules in the ruleset can reference all rules in the rulesets defined in the:
l Same application
l Rulesets belonging to any built-on application
Rules in the ruleset cannot reference rules outside the current application stack or above the defining
application.
In the following example, all rulesets are configured as AV. The shaded and unshaded cells represent
applications. The loan application is built on a loan framework.

18
©2018 Pegasystems
 Ruleset Mode
LoanPricing Can call all other rulesets listed
LoanUnderwriting Can call all other rulesets listed
LoanPricingFW Can call LoanUnderwritingFW but not shaded rulesets
LoanUnderwritingFW Can call LoanPricingFW but not shaded rulesets

AV allows for codependent rulesets within the same application. That is, rules in LoanPricing can
reference rules in LoanUnderwriting, and rules in LoanUnderwriting can reference rules in LoanPricing.
Each ruleset in the application has a version. When AV mode is used, the application defines the
ruleset versions accessible for a given ruleset. For example, ruleset LoanPricing:01-01-03 can access
ruleset version 01-01-01 to 01-01-03 of the ruleset LoanUnderwriting and 01-01-01 to 01-02-10 of the
LoanPricingFW and LoanUnderwritingFW rulesets.
When AV mode is selected, if you change the application definition, the rules may become invalid.
Invalid rules might cause serious errors at run time. Use the Validation tool (DesignerStudio >
Application >Tools > Validation) to quickly identify invalid rules in the application.

Ruleset validation mode

When you use RV mode, each ruleset version defines one or more ruleset versions on which the ruleset
version depends. For example, if you create a ruleset Myco:01-01-01 that uses rules in MyCoInt:01-01-01
and Customer:01-01-01, then MyCoInt:01-01-01 and Customer:01-01-01 ruleset versions must be
specified as a prerequisite. Only rules in the ruleset versions that are specified as prerequisites (and
their prerequisites) can be referenced from the ruleset.
For example, if MyCo:01-01-01 specifies Customer:01-01-03 as a prerequisite, rules in version 01-01-01
to 01-01-03 of the customer ruleset can be referenced.

Ruleset prerequisites
If your ruleset version does not have any prerequisite ruleset versions, you need to specify the base
product ruleset Pega-ProcessCommander as a prerequisite.

19
©2018 Pegasystems
The Pega-ProcessCommander ruleset lists all product rulesets. You do not need to list any product
rulesets below Pega-ProcessCommander. There is a 99 patch version of the Pega-ProcessCommander
ruleset available in the product. Use that ruleset version as a prerequisite to avoid having to update
the ruleset after product updates. For example, if the product is updated from 07-10-13 to 07-10-18,
you do not need to update the rule prerequisites since the 99 version automatically picks the highest
patch for the ruleset version.
Ruleset prerequisites cannot be cyclic. For example, if Alpha:01-01-01 defines Beta:01-01-01 as a
prerequisite, then Beta:01-01-01 cannot define Alpha:01-01-01 as a prerequisite.

Mixing application ruleset validation modes

You can mix rulesets that use AV and RV.
l Rulesets with another ruleset in brackets — for example, MyCoPL [MyCo] — next to them use RV.
The ruleset in brackets is the prerequisite ruleset.
l Rulesets without a ruleset with brackets next to them use AV.
With RV, you cannot call AV rulesets that are not in the prerequisites.

20
©2018 Pegasystems
 Name Mode
LoanPricing Can call all other rulesets listed
LoanUnderwriting Can call rules in all other rulesets including LoanPricing
MyCoPL [MyCo] Can call rules in MyCo but not in LoanUnderwriting, LoanPricing,
LoanPricingFW, or LoanUnderwritingFW
LoanPricingFW Cannot call rules in MyCoPL, LoanUnderwriting, or LoanPricing
LoanUnderwritingFW Cannot call rules in MyCoPL, LoanUnderwriting, or LoanPricing
MyCo [PRPC] Can only call rules in MyCo

Ruleset validation best practices

Follow these best practices when configuring rulesets.
l Only use RV for rulesets that are designed to be used across multiple applications, such as
organizational rulesets, to make them easily portable and prevent introduction of dependencies on
a specific application.
l Create applications for common rulesets; use the built-on functionality to include common rulesets
in the application.
l Include unlocked AV rulesets in one application only. This prevents AV rulesets from referring to
rules that may not exist in applications that do not contain the ruleset.
l Run the Validation tool after critical changes/milestones have been implemented (for example,
changes to the application ruleset list or built-on application as well as changes made before

21
©2018 Pegasystems
 lock/export).
Note: For more information about the Validation tool, see the Help topic Validation tool.
KNOWLEDGE CHECK

Which ruleset validation mode allows for codependent rulesets?

Application validation (AV)

22
©2018 Pegasystems
The ruleset list
While ruleset validation governs rule development and import, the ruleset list, sometimes referred to
as the ruleset stack, governs rule execution at run time. Because ruleset validation is enforced during
development, the system does not need to validate the rulesets during run-time processing.
The ruleset list indicates the rulesets that are available to the application for a given operator session.
The ruleset list is available in the operator profile Operator > Profile.

Note: The order of the rulesets is important. The rule resolution algorithm refers to the order of the
ruleset in the ruleset list. Rulesets at the top of the list have higher precedence.
The ruleset list is assembled by Pega when an operator logs in to the application. The process begins
by locating the versioned application rule referenced on the access group of the operator.
Note: In rare configurations, the access group is provided as part of the requestor definition,
organization, or division record.
The ruleset list consists of rulesets referenced on the application form. The built-on applications are
processed repeatedly until the PegaRULES application is located.
The ruleset list is built by stepping through the built-on applications until the PegaRULES application is
located. First the PegaRULES ruleset list is added to the ruleset list. Then the built-on applications are
processed recursively adding each application’s ruleset to the ruleset list on top of the previously
added rulesets.
For example, the PegaRULES application is at the base, the HRFW application is built on top of
PegaRULES, and the HRApps application is built on top of HRFW.

23
©2018 Pegasystems
If you are allowed to check out rules, a personal ruleset is added to the top of the list. The personal
ruleset has the name of the operator ID and contains the rules checked out by the operator.

The ruleset list for the application with built-on applications can be viewed on the ruleset list landing
page (Designer Studio > Application > Structure > RuleSet Stack).
KNOWLEDGE CHECK

The ruleset list indicates the rulesets that are available to the application for _______________.
a given operator session

24
©2018 Pegasystems
How to manage changes to rules in a ruleset
Rules are the source code of an application. During development, changes to rules need to be
managed to ensure that:
l Rules belonging to a release that has been promoted are not updated
l Rules are configured in a coordinated manner to avoid rules being updated simultaneously

Ruleset locking
You can lock a ruleset to prevent changes using the Lock and Save button. Typically, you lock rulesets
when development has reached a specific state and the application is ready to be promoted to testing.
You cannot add or update rules in a locked ruleset.

Rule check-out and check-in

Applications are typically developed by a team. Multiple team members may check out rules to work on
the same application in a coordinated way. The check-out feature ensures that one rule is not being
edited by different team members at the same time.
The system enforces use of check-out and check-in operations when a ruleset has the check-out facility
turned on. Before you can change that rule, you must perform either the standard check-out or private
check-out operation.

Check out a rule

When you check out a rule, you are creating a private copy of the rule that you can modify and test.
On the Security tab on the ruleset, select Use check-out? to enable check-out.

25
©2018 Pegasystems
On the Operator record Security tab, operators need to have the Allow Rule Check out selected in
order to update rules in rulesets that require check-out.

The check-out button displays on rules that are in unlocked rulesets. If a developer checks out a rule,
no one else may check the rule out until it is checked back in by the developer.
If a rule is not available for check-out, it is already checked out by someone else, or in a locked ruleset
version.
When the rule is in a locked ruleset version, the private edit button is displayed instead of the check-
out button. Private edit is a special case of the standard check-out that allows a developer to prototype
or test changes to a rule that is not available for standard check-out. When an operator checks out or
selects private edit for a rule, a copy of the rule is placed in the personal ruleset.
We can view our checkouts and private edits in the Private Explorer or by using the check mark icon in
the header.

26
©2018 Pegasystems
Checking in a rule
When a rule is checked in, the checked-in rule replaces the original base rule. Add a comment
describing the changes to the rule. The check-in comments can be viewed on the rule History tab.
Use the bulk action feature to check-in, open, or delete several checked out rules at the same time. The
bulk action feature is located in the Private Explorer menu or under the check mark icon in the header.

KNOWLEDGE CHECK

List two reasons a rule is not available for checkout.

The rule is already checked out by someone else. The rule is in a locked ruleset

27
©2018 Pegasystems
 Branching rulesets for parallel
development
Introduction to branching rulesets for
parallel development
In this lesson, you learn how to use branches to enable parallel development work to take place within
an isolated ruleset without impacting other development teams.
After this lesson, you should be able to:
l Explain the role of branches in development
l List the benefits of using branches
l Develop in parallel using branches
l Create a development branch
l Merge the contents of a branch into an application

28
©2018 Pegasystems
Parallel development
When multiple teams are working in the same application rulesets, coordinating changes across teams
is a challenge. When development teams configure an application in parallel, rule changes might
result in conflicts. Resolving conflicts disrupts the overall project and may delay time to delivery.
Pega 7 uses branches to help teams manage parallel development in distributed environments. A
branch is a container for rulesets with records that are undergoing rapid change and development.
The rulesets associated with a branch are called branch rulesets.
A branch ruleset:
l Is based on (branched from) another ruleset
l Contains rules that are in active development in the associated branch
In Pega, you create a branch for each team. These branches allow each team to create and update
rules without impacting other teams.
The following scenario describes how branches allow multiple teams to make rule update changes in
parallel.
Team Alpha and Team Beta are developing an HR Onboarding application. Team Alpha is assigned to
develop a new UI feature. Team Beta is assigned to work on candidate profile information. While each
team works independently, both features involve changes to rules in the same rulesets: HR, HRApps,
and HRAppsInt.

Using branches and branch rulesets, each team creates its own development branch. When the rule
updates are complete, each team resolves conflicts the system detects between the branch rules and

29
©2018 Pegasystems
other instances of the rules. After the team resolves rule conflicts, the system merges the updated
branch rules into the original application.
Branches allow each team to work within an isolated space (the branch) without affecting functionality
other teams are developing. They are especially useful on large development projects, where multiple
teams work simultaneously on the rules in an application. Each team works on their changes
independently. All members of a team can see each other's work, while isolating the development
changes from other teams. Changes do not affect other teams until the changes are stable, conflicts
are resolved, and approval is granted to make the changes available to all development teams.
KNOWLEDGE CHECK

Describe two advantages of branching.

Two or more development teams can configure an application in parallel. Rule development takes
place within an isolated space (the branch) without affecting functionality in the source rules.

30
©2018 Pegasystems
How to develop in parallel by branching
rulesets
To manage the independent development of features that share rulesets, each Pega development
team creates its own branch and branch rulesets. 
For example, two development teams are building features for a new application. Changes made by
each team impact the same application rulesets. To develop rules in parallel using branched rulesets,
each team follows these steps:
1. Creates a team application built on the main application
2. Creates one or more development branches in the team application
3. Grants access to the team application
4. Creates or configures rules using the branch
5. Merges each branch into the application rulesets when development in branches is complete and
stable
When the work is done, the team resolves conflicts the system detects between its branch and the
application. After resolving any conflicts, the team merges the contents of the branch into the main
application rulesets.

Create a team application

First, Team A and Team B each create a development team application built on the main application.
Team application names typically reflect the base application, team name, or the focus of the team. For
example, for a base application named HRApps, the development team working on the layout of the
user portal might name the team application HRAppsPortalFeature.
Open the main application rule and perform a Save As to create the team application. Under the list of
Built on applications, configure the team application to reference the main application.
The following image displays a team application rule with a branch.

31
©2018 Pegasystems
KNOWLEDGE CHECK

Why do you create a team application? 

You create a team application to allow your team to manage the branches they use and not impact
other teams.

Create branches in the team application

After you create the team application, you define branches in the application and add them to the
application record for the team application. Specify a unique name for the branch that identifies the
feature being configured. Pega limits the name of each branch to 16 characters.
Important: Branch names are visible across all the applications on a system. When creating a branch,
use a name that identifies the appropriate application, such as Expense[Feature]. This avoids
confusion when development teams attempt to add branches to their applications.
Note: When using multiple branches in your application, ensure that the order of the branches in the
application definition rule form matches the order in which rules should be resolved for this
application.

32
©2018 Pegasystems
Grant access to the team application
Create an access group that references the team application. To name the access group, include the
application name plus the standard user type, such as HRAppsPOAdmn. When you create the access
group:
l Verify that the access roles are sufficient to develop and test the application.
l Reference the work pool for the main application.
l Specify the correct portal, such as the Developer portal for application developers.
Tip: When creating access groups for each team, start by copying the access groups for the original
application.

Configure rules using branches

You have created:
l A team development application, built on the main application
l Branches defined in that team development application
The development team members can now implement the planned enhancements in the branches.
To update an existing rule, save a copy of the base rule into the same ruleset, but select the desired
branch and work on that copy. When selecting a branch, Pega stores the rule in a branch ruleset
created automatically for you.
Tip: If a ruleset is configured to support check out, you can check out a record directly to the branch.
Checking out a record to a branch copies the rule in its current state to the branch and checks out the
new record for configuration.
To create new rules, save them directly into a branch and select a ruleset where the new rule will be
merged into once development is complete. You must check in all rules to the branch ruleset before
merging.

33
©2018 Pegasystems
 34
©2018 Pegasystems
How to merge changes from a branched
ruleset
You use the Merge Branch Rulesets wizard to move branch contents into the base rulesets. Multiple
teams working on the same application might create conflicts such as branching the same base
rulesets, or modifying the core rules at the same time. The Merge Branch Ruleset wizard helps identify
potential conflicts so that you can address them before moving your changes.
Note: Changes to rulesets need close coordination. For example, if a developer tries to check in a rule
that already exists in a higher-numbered ruleset version, a warning appears in the rule form. The
owner of the higher-numbered ruleset version should be informed.
KNOWLEDGE CHECK

Before moving the updated rules into the base rulesets, you first _____________.
identify any conflicts between your changes using the Merge Branch Ruleset wizard

Merge branches when development is stable

Move the new and updated records from the branch to the base rulesets when development activity in
the branch has reached a stable point. This makes the newest updates available to the wider
development team. When you merge a branch into the application, you can either delete the branch if
development is complete, or maintain the branch to support additional development of the feature.
Before you begin the merge process, view the contents of the branch on the Content tab of the Branch
landing page. Content information includes the changed rules, ruleset and the user ID of the individual
who updated the rule.
Important: You must check in all rules to the branch ruleset before merging. Use the Content tab to
identify developers that may be responsible for checked-out rules.
To view the possible rule conflicts, guardrail warnings and unit test coverage, on the branch rule, select
the Branch quality tab. Resolve the guardrail warnings and merge conflicts before beginning the
merge process.
Next, select Merge from the Actions menu to begin the merge process. Pega presents a dialog
confirming the branch to merge. Click Proceed to display source and target ruleset information.

35
©2018 Pegasystems
For each ruleset, select the ruleset version into which to copy rules from the branch. The wizard
defaults to the highest unlocked version of the ruleset in the base application. You can also elect to
create a new, unlocked ruleset version for merging rules. Complete the process by selecting Merge.
The wizard displays a confirmation page. The following image shows a Merge Branch Rulesets wizard
confirmation page.

The final step is to delete the branch from the application to avoid accidental duplicate merges.
For more information on how to merge branches, see the Help topic Merging branches.

36
©2018 Pegasystems
KNOWLEDGE CHECK

How do you ensure there are no rule conflicts or guardrail warnings in the merge branch
candidate?
You can view possible rule conflicts and guardrail warnings in the branch rule on the Branch quality
tab.

37
©2018 Pegasystems
 Rule resolution
Introduction to rule resolution
In this lesson, you learn about rule resolution. Rule resolution finds the best or most appropriate rule
instance to apply in a situation.
After this lesson, you should be able to:
l State the rule resolution process
l Influence rule resolution results by adjusting rule availability

38
©2018 Pegasystems
Rule resolution
Rule resolution is a search algorithm used to find the most appropriate instance of a rule to execute
in any situation.
Rule resolution occurs whenever a rule is needed to accomplish processing of a case. As you create
applications, the choices you make when defining the values for the key parts of a rule determine how
Pega finds the rule through rule resolution.
Rule resolution applies to most rules that are instances of classes derived from the abstract Rule- base
class. The following are examples of instances of rules derived from the abstract Rule- base class:
l Case types (Rule-Obj-CaseType)
l Properties (Rule-Obj-Property)
l UI rules such as Sections (Rule-HTML-Section) and Harnesses (Rule-HTML-Harness)
l Ruleset names (Rule-Ruleset-Name)
l Ruleset versions (Rule-RuleSet-Version)
Rule resolution does not apply to records that are instances of classes derived from any other abstract
base class such as Data-, System-, or Work-. The following are examples of instances of rules derived
from the abstract System- base class;
l Operator IDs (Data-Admin-Operator-ID)
l Email listeners (Data-Admin-Connect-EmailListener)
l Operator's favorites (System-User-MyRules)
l The rule check-in process (Work-RuleCheckIn)
Tip: A rule's type is defined by the class from which the rule is derived. For example, the rule type of a
rule derived from Rule-HTML-Section is called a section rule. The rule type of a rule derived from Data-
Admin-Operator-ID is called an operator ID rule.
KNOWLEDGE CHECK

Rule resolution applies to most rules that are instances of classes derived from the _______
base class.
abstract Rule-

Inputs to the rule resolution algorithm

Inputs to the rule resolution algorithm include:
l Predefined rule keys that are used as a unique identifier, such as the Apply to: class, rule name, and
rule type
l User's ruleset list
l Class hierarchy of the rule in question
l Circumstances such as the value of a property, or time and date restrictions

39
©2018 Pegasystems
l Availability of the rule
l User's access roles and privileges
The output of the resolution process is the first rule found that matches all of the input criteria.

40
©2018 Pegasystems
How the rule resolution process works
Rule Resolution is the process Pega uses to determine the most appropriate rule to execute.

When a rule is referenced in a Pega application, rule resolution attempts to locate instances of the rule
in the rules cache. If instances of the referenced rule are found, rule resolution finds the best instance
of the rule and checks for duplicates. Then Pega confirms the rule is available for use. Finally, Pega
verifies the user is authorized to use the rule.
If instances of the rule are not found in the rules cache, Pega runs a special sub-process to populate
the rules cache.
The point of the rule resolution is to return the most appropriate rule to satisfy the need of a specific
user for a specific purpose.

Find the rule in the rules cache

If rule resolution was already run for the rule, the rules cache has a list of all possible rule candidates.
For example, the referenced rule is a section rule named CreateRequest for a Purchase Request case.
The requestor (the user working on the case) has the Purchasing:02-01-05 ruleset in their ruleset stack.
Pega 7 searches the Rules Cache for a list of all possible rule candidates for the rule in question.
The rules cache contains three rule candidates.

Apply Rule Rule name Availabili Ruleset Versio Qualifier Privileg

to: class type ty n e
TGB- Rule- CreateReque Available Purchasi 02-01- Supplier=Restrict
Purchasin HTML- st ng 05 ed
g-Work Sectio
n
TGB- Rule- CreateReque Available Purchasi 02-01- < 01 June 2000
Purchasin HTML- st ng 05
g-Work Sectio

41
©2018 Pegasystems
 Apply Rule Rule name Availabili Ruleset Versio Qualifier Privileg
to: class type ty n e
n
TGB- Rule- CreateReque Available Purchasi 02-01-
Purchasin HTML- st ng 05
g-Work Sectio
n

Find the best instance and check for duplicates

In this step, the rule resolution algorithm determines which rule candidate is a first, best match. A first,
best match is determined by an exact match of a property or date circumstance, or a default rule if no
exact circumstance matches are found.
When a rule that matches any of these conditions is found, the rule resolution algorithm checks
whether the next rule in the list is equally correct. If a subsequent match is found, Pega sends a
message that there are duplicate rules and stops processing. If no other matches are found, Pega
prepares to use the rule that matched the listed conditions.
Continuing with the example, the value of .Supplier in the Purchase Request case is set to Open. The
first condition — .Supplier=Restricted — is not met, so the rule candidate is skipped and Pega moves to
the next rule in the list.

Apply Rule Rule name Availabili Ruleset Versio Qualifier Privileg

to: class type ty n e
TGB- Rule- CreateReque Available Purchasi 02-01- Supplier=Restrict
Purchasin HTML- st ng 05 ed
g-Work Sectio
n
TGB- Rule- CreateReque Available Purchasi 02-01- < 01 June 2000
Purchasin HTML- st ng 05
g-Work Sectio
n
TGB- Rule- CreateReque Available Purchasi 02-01-
Purchasin HTML- st ng 05
g-Work Sectio
n

The next rule candidate has a date circumstance defined, so Pega compares the date circumstance
against the current system date.
Continuing with the example, the next condition is a date range specified as Before 01 June, 2000.
Assume the current system date is 15 August 2000.

42
©2018 Pegasystems
 Apply to: Rule Rule name Availabilit Ruleset Versio Qualifie Privileg
class type y n r e
TGB- Rule- CreateReques Available Purchasin 02-01-05 < 01 June
Purchasin HTML- t g 2000
g-Work Sectio
n
TGB- Rule- CreateReques Available Purchasin 02-01-05
Purchasin HTML- t g
g-Work Sectio
n

The date range circumstance is not met, so the rule candidate is skipped and Pega moves to the next
rule in the list. The next rule candidate does not have a qualifier, so the system selects this rule.

Apply to: Rule Rule name Availabilit Ruleset Versio Qualifie Privileg
class type y n r e
TGB- Rule- CreateReques Available Purchasin 02-01-05
Purchasin HTML- t g
g-Work Sectio
n

KNOWLEDGE CHECK

During rule resolution, a first, best match is determined by ______________.

an exact match of a property or date circumstance

KNOWLEDGE CHECK

During rule resolution, the _____________ rule is selected if no exact circumstance matches are
found.
default

Confirm the rule is available for use

In this step, the rule resolution algorithm checks to see if the Availability of the rule is set to Blocked. If
the rule is blocked, the system sends a message that it could not find an appropriate rule to use.
Continuing with the example, the availability of the rule candidate is set to Available, so the rule is
considered available to run.

43
©2018 Pegasystems
 Apply to: Rule Rule name Availabilit Ruleset Versio Qualifie Privileg
class type y n r e
TGB- Rule- CreateReques Available Purchasin 02-01-05
Purchasin HTML- t g
g-Work Sectio
n

Verify the user is authorized to use the rule

In this final step, the rule resolution algorithm verifies that the user has authorization to access the
selected rule. If the user has all of the privileges required by the selected rule, the rule is executed. If
the user does not have any of the privileges required by the rule, Pega sends a message that it could
not find an appropriate rule to execute.
The rule does not list a required privilege, so the rule is selected and executed.

Apply to: Rule Rule name Availabilit Ruleset Versio Qualifie Privileg
class type y n r e
TGB- Rule- CreateReques Available Purchasin 02-01-05
Purchasin HTML- t g
g-Work Sectio
n

44
©2018 Pegasystems
How the rules cache is populated
Pega uses a caching mechanism called the Rules Cache to help ensure rule resolution operates
efficiently.
When your application references a rule, Pega checks the rules cache for the referenced rule. If the
referenced rule is not available in the rules cache, Pega uses a multiple-step process to populate the
rules cache.

To populate the rules cache, the rule resolution algorithm first creates a list of all rules that match the
purpose of the rule in question. Next, rule candidates marked as Not Available are removed from the
list. Then the rule resolution algorithm uses the operator's Ruleset list to determine which rule
candidates the operator can access. The rule resolution algorithm then removes all rule candidates not
defined in a class in the ancestor tree. The rule resolution algorithm then ranks the remaining rule
candidates. Finally, the rule resolution algorithm adds the remaining rule candidates to the Rules
Cache.
The referenced rule used in the following examples is a section rule named CreateRequest for a
Purchase Request case. This example helps illustrate the rule resolution process.

Choose all instances with the correct purpose

In this step, the rule resolution algorithm creates a list of all rules that match the purpose of the
referenced rule.
Note: Remember, the purpose of a rule is defined by a combination of all the key properties of a rule,
except the Apply to: class on which the rule is defined. For example, the key properties of a section rule
include the Apply to: class, the rule type, and the rule name.
In the example, all HTML section rules named CreateRequest are collected into a list. There can be many
instances of the rule in the initial list of rule candidates.
Note: The Apply to: class is displayed in this list to help provide context where each instance of the
rule in question is found.

Apply to: class Rule type Rule name

TGB-Purchasing-Work-PurchaseRequest Rule-HTML-Section CreateRequest

45
©2018 Pegasystems
 Apply to: class Rule type Rule name
TGB-Purchasing-Work-PurchaseRequest Rule-HTML-Section CreateRequest
TGB-Purchasing-Work-PurchaseRequest Rule-HTML-Section CreateRequest
TGB-Purchasing-Work-PurchaseRequest Rule-HTML-Section CreateRequest
TGB-Purchasing-Work-PurchaseRequest Rule-HTML-Section CreateRequest
TGB-Purchasing-Work-PurchaseRequest Rule-HTML-Section CreateRequest
TGB-Purchasing-Work-PurchaseOrder Rule-HTML-Section CreateRequest
TGB-Purchasing-Work-PurchaseOrder Rule-HTML-Section CreateRequest
TGB-Purchasing-Work Rule-HTML-Section CreateRequest
TGB-Purchasing-Work Rule-HTML-Section CreateRequest
TGB-Purchasing-Work Rule-HTML-Section CreateRequest
TGB-Purchasing-Work Rule-HTML-Section CreateRequest
TGB-Purchasing-Work Rule-HTML-Section CreateRequest
TGB Rule-HTML-Section CreateRequest
TGB Rule-HTML-Section CreateRequest
TGB Rule-HTML-Section CreateRequest
TGB Rule-HTML-Section CreateRequest
TGB Rule-HTML-Section CreateRequest
TGB Rule-HTML-Section CreateRequest
SAE-Quoting-Work-EnterQuote Rule-HTML-Section CreateRequest
SAE-Quoting-Work-EnterQuote Rule-HTML-Section CreateRequest
SAE-Quoting-Work Rule-HTML-Section CreateRequest
SAE Rule-HTML-Section CreateRequest

Discard rules where Availability = Not Available

In this step, the rule resolution algorithm filters the list of rule candidates and removes any rules
where the Availability of a rule is set to Not Available.
Continuing with the example, the rule resolution algorithm finds three rules where the Availability of a
rule is set to Not Available. The rules are removed from the list of rule candidates.

Apply to: class Rule type Rule name Availability

TGB-Purchasing-Work-PurchaseRequest Rule-HTML-Section CreateRequest Not Available
TGB-Purchasing-Work-PurchaseRequest Rule-HTML-Section CreateRequest Available

46
©2018 Pegasystems
 Apply to: class Rule type Rule name Availability
TGB-Purchasing-Work-PurchaseRequest Rule-HTML-Section CreateRequest Withdrawn
TGB-Purchasing-Work-PurchaseRequest Rule-HTML-Section CreateRequest Available
TGB-Purchasing-Work-PurchaseRequest Rule-HTML-Section CreateRequest Available
TGB-Purchasing-Work-PurchaseRequest Rule-HTML-Section CreateRequest Blocked
TGB-Purchasing-Work-PurchaseOrder Rule-HTML-Section CreateRequest Available
TGB-Purchasing-Work-PurchaseOrder Rule-HTML-Section CreateRequest Available
TGB-Purchasing-Work Rule-HTML-Section CreateRequest Not Available
TGB-Purchasing-Work Rule-HTML-Section CreateRequest Available
TGB-Purchasing-Work Rule-HTML-Section CreateRequest Available
TGB-Purchasing-Work Rule-HTML-Section CreateRequest Available
TGB-Purchasing-Work Rule-HTML-Section CreateRequest Available
TGB Rule-HTML-Section CreateRequest Available
TGB Rule-HTML-Section CreateRequest Available
TGB Rule-HTML-Section CreateRequest Available
TGB Rule-HTML-Section CreateRequest Available
TGB Rule-HTML-Section CreateRequest Available
TGB Rule-HTML-Section CreateRequest Available
SAE-Quoting-Work-EnterQuote Rule-HTML-Section CreateRequest Available
SAE-Quoting-Work-EnterQuote Rule-HTML-Section CreateRequest Not Available
SAE-Quoting-Work Rule-HTML-Section CreateRequest Available
SAE Rule-HTML-Section CreateRequest Available

Discard inapplicable rulesets and versions

In this step, the rule resolution algorithm uses the operator's Ruleset list to determine which candidate
rules the operator can access.
Tip: The Ruleset list is a combination of the ruleset name and a Major-Minor version number.
To be included in the results, each rule candidate must belong to a ruleset listed in the operator's
ruleset list. Each rule must have the same Major version number, and a Minor version number less
than or equal to the specified Minor version number listed in the operator's ruleset list.
Continuing with the example, assume the operator's ruleset list includes Puchasing:02-01 and TGB:03-
01.
The three rules in the Purchasing:01-01-01 ruleset are eliminated because they do not match the major
version as defined in the operator's ruleset list (Purchasing:02-01).

47
©2018 Pegasystems
Apply to: class Rule type Rule name Availability Ruleset Version
TGB-Purchasing-Work- Rule-HTML- CreateRequest Available Purchasing 02-02-01
PurchaseRequest Section
TGB-Purchasing-Work- Rule-HTML- CreateRequest Withdrawn Purchasing 02-01-10
PurchaseRequest Section
TGB-Purchasing-Work- Rule-HTML- CreateRequest Available Purchasing 02-01-05
PurchaseRequest Section
TGB-Purchasing-Work- Rule-HTML- CreateRequest Available Purchasing 02-01-01
PurchaseRequest Section
TGB-Purchasing-Work- Rule-HTML- CreateRequest Blocked Purchasing 01-01-01
PurchaseRequest Section
TGB-Purchasing-Work- Rule-HTML- CreateRequest Available Purchasing 02-01-01
PurchaseOrder Section
TGB-Purchasing-Work- Rule-HTML- CreateRequest Available Purchasing 01-01-01
PurchaseOrder Section
TGB-Purchasing-Work Rule-HTML- CreateRequest Available Purchasing 02-01-05
Section
TGB-Purchasing-Work Rule-HTML- CreateRequest Available Purchasing 02-01-05
Section
TGB-Purchasing-Work Rule-HTML- CreateRequest Available Purchasing 02-01-05
Section
TGB-Purchasing-Work Rule-HTML- CreateRequest Available Purchasing 02-01-01
Section
TGB Rule-HTML- CreateRequest Available Purchasing 01-01-01
Section
TGB Rule-HTML- CreateRequest Available TGB 03-01-01
Section
TGB Rule-HTML- CreateRequest Available TGB 02-10-01
Section
TGB Rule-HTML- CreateRequest Available TGB 02-10-01
Section
TGB Rule-HTML- CreateRequest Available TGB 02-01-01
Section
TGB Rule-HTML- CreateRequest Available TGB 01-01-01
Section
SAE-Quoting-Work- Rule-HTML- CreateRequest Available Quoting 01-01-06

48
©2018 Pegasystems
 Apply to: class Rule type Rule name Availability Ruleset Version
EnterQuote Section
SAE-Quoting-Work Rule-HTML- CreateRequest Available Quoting 01-01-01
Section
SAE Rule-HTML- CreateRequest Available SAE 01-01-01
Section

The rule in the Purchasing:02-02-01 ruleset is also eliminated because the minor version number
(Purchasing:02- 02) is higher than the minor version number defined in the operator's ruleset list
(Purchasing:02- 01).

Apply to: class Rule type Rule name Availability Ruleset Version
TGB-Purchasing-Work- Rule-HTML- CreateRequest Available Purchasing 02-02-01
PurchaseRequest Section
TGB-Purchasing-Work- Rule-HTML- CreateRequest Withdrawn Purchasing 02-01-10
PurchaseRequest Section
TGB-Purchasing-Work- Rule-HTML- CreateRequest Available Purchasing 02-01-05
PurchaseRequest Section
TGB-Purchasing-Work- Rule-HTML- CreateRequest Available Purchasing 02-01-01
PurchaseRequest Section
TGB-Purchasing-Work- Rule-HTML- CreateRequest Available Purchasing 02-01-01
PurchaseOrder Section
TGB-Purchasing-Work Rule-HTML- CreateRequest Available Purchasing 02-01-05
Section
TGB-Purchasing-Work Rule-HTML- CreateRequest Available Purchasing 02-01-05
Section
TGB-Purchasing-Work Rule-HTML- CreateRequest Available Purchasing 02-01-05
Section
TGB-Purchasing-Work Rule-HTML- CreateRequest Available Purchasing 02-01-01
Section
TGB Rule-HTML- CreateRequest Available TGB 03-01-01
Section
TGB Rule-HTML- CreateRequest Available TGB 02-10-01
Section
TGB Rule-HTML- CreateRequest Available TGB 02-10-01
Section
TGB Rule-HTML- CreateRequest Available TGB 02-01-01

49
©2018 Pegasystems
 Apply to: class Rule type Rule name Availability Ruleset Version
Section
TGB Rule-HTML- CreateRequest Available TGB 01-01-01
Section
SAE-Quoting-Work- Rule-HTML- CreateRequest Available Quoting 01-01-06
EnterQuote Section
SAE-Quoting-Work Rule-HTML- CreateRequest Available Quoting 01-01-01
Section
SAE Rule-HTML- CreateRequest Available SAE 01-01-01
Section

Of the rules listed in the TGB rulesets, only one rule matches the current major version listed in the
operator's ruleset list (TGB:03-01). All other rules in the TGB rulesets are eliminated.

Apply to: class Rule type Rule name Availability Ruleset Version
TGB-Purchasing-Work- Rule-HTML- CreateRequest Withdrawn Purchasing 02-01-10
PurchaseRequest Section
TGB-Purchasing-Work- Rule-HTML- CreateRequest Available Purchasing 02-01-05
PurchaseRequest Section
TGB-Purchasing-Work- Rule-HTML- CreateRequest Available Purchasing 02-01-01
PurchaseRequest Section
TGB-Purchasing-Work- Rule-HTML- CreateRequest Available Purchasing 02-01-01
PurchaseOrder Section
TGB-Purchasing-Work Rule-HTML- CreateRequest Available Purchasing 02-01-05
Section
TGB-Purchasing-Work Rule-HTML- CreateRequest Available Purchasing 02-01-05
Section
TGB-Purchasing-Work Rule-HTML- CreateRequest Available Purchasing 02-01-05
Section
TGB-Purchasing-Work Rule-HTML- CreateRequest Available Purchasing 02-01-01
Section
TGB Rule-HTML- CreateRequest Available TGB 03-01-01
Section
TGB Rule-HTML- CreateRequest Available TGB 02-10-01
Section
TGB Rule-HTML- CreateRequest Available TGB 02-10-01
Section

50
©2018 Pegasystems
 Apply to: class Rule type Rule name Availability Ruleset Version
TGB Rule-HTML- CreateRequest Available TGB 02-01-01
Section
TGB Rule-HTML- CreateRequest Available TGB 01-01-01
Section
SAE-Quoting-Work- Rule-HTML- CreateRequest Available Quoting 01-01-06
EnterQuote Section
SAE-Quoting-Work Rule-HTML- CreateRequest Available Quoting 01-01-01
Section
SAE Rule-HTML- CreateRequest Available SAE 01-01-01
Section

The rules listed in the Quoting and SAE rulesets are eliminated because the rulesets are not listed in
the operator's ruleset list.

Apply to: class Rule type Rule name Availability Ruleset Version
TGB-Purchasing-Work- Rule-HTML- CreateRequest Withdrawn Purchasing 02-01-10
PurchaseRequest Section
TGB-Purchasing-Work- Rule-HTML- CreateRequest Available Purchasing 02-01-05
PurchaseRequest Section
TGB-Purchasing-Work- Rule-HTML- CreateRequest Available Purchasing 02-01-01
PurchaseRequest Section
TGB-Purchasing-Work- Rule-HTML- CreateRequest Available Purchasing 02-01-01
PurchaseOrder Section
TGB-Purchasing-Work Rule-HTML- CreateRequest Available Purchasing 02-01-05
Section
TGB-Purchasing-Work Rule-HTML- CreateRequest Available Purchasing 02-01-05
Section
TGB-Purchasing-Work Rule-HTML- CreateRequest Available Purchasing 02-01-05
Section
TGB-Purchasing-Work Rule-HTML- CreateRequest Available Purchasing 02-01-01
Section
TGB Rule-HTML- CreateRequest Available TGB 03-01-01
Section
SAE-Quoting-Work- Rule-HTML- CreateRequest Available Quoting 01-01-06
EnterQuote Section
SAE-Quoting-Work Rule-HTML- CreateRequest Available Quoting 01-01-01

51
©2018 Pegasystems
 Apply to: class Rule type Rule name Availability Ruleset Version
Section
SAE Rule-HTML- CreateRequest Available SAE 01-01-01
Section

KNOWLEDGE CHECK

Assume an operator's ruleset list includes Loans:01-01. Why would a candidate rule found in
Loans:01-02 not be included in the results of the rule resolution process?
To be included in the results, each candidate rule must have the same Major version number, and a
Minor version number less than or equal to the specified Minor version number listed in the
operator's ruleset list.

Discard all candidates not defined in a class in the

ancestor tree
In this step, the rule resolution algorithm examines the Apply to: class in the list of candidate rules to
determine if the remaining candidate rules are in the inheritance hierarchy of the referenced rule.
Note: The ancestor tree refers to a rule’s inheritance.
To be included in the results, the Apply to: class of the remaining candidate rules must match the
ancestor tree of the referenced rule. Only rules found in the ancestor tree of the referenced rule — by
either pattern or direct inheritance — will be retained in the list.
Important: A class must have the Use class-based inheritance to arrive at the correct rule to execute
check box selected in the class definition to be considered in this step.
Continuing with the example, the referenced rule has an Apply to: class of TGB-Purchasing-Work-
PurchaseRequest. There is one candidate rule not in the ancestor tree, so it is removed from the list.

Apply to: class Rule type Rule name Availability Ruleset Version
TGB-Purchasing-Work- Rule-HTML- CreateRequest Withdrawn Purchasing 02-01-10
PurchaseRequest Section
TGB-Purchasing-Work- Rule-HTML- CreateRequest Available Purchasing 02-01-05
PurchaseRequest Section
TGB-Purchasing-Work- Rule-HTML- CreateRequest Available Purchasing 02-01-01
PurchaseRequest Section
TGB-Purchasing-Work- Rule-HTML- CreateRequest Available Purchasing 02-01-01
PurchaseOrder Section
TGB-Purchasing-Work Rule-HTML- CreateRequest Available Purchasing 02-01-05
Section

52
©2018 Pegasystems
 Apply to: class Rule type Rule name Availability Ruleset Version
TGB-Purchasing-Work Rule-HTML- CreateRequest Available Purchasing 02-01-05
Section
TGB-Purchasing-Work Rule-HTML- CreateRequest Available Purchasing 02-01-05
Section
TGB-Purchasing-Work Rule-HTML- CreateRequest Available Purchasing 02-01-01
Section
TGB Rule-HTML- CreateRequest Available TGB 03-01-01
Section

KNOWLEDGE CHECK

Assume the referenced rule has an Apply to: class of TGB-HRApps-Work-Onboarding. Why

would a candidate rule with an Apply to: class of TGB-HRApps-Work be retained in the list of rule
candidates?
Rules found in the ancestor tree of the rule in question — by either pattern or direct inheritance —
are retained in the list of rule candidates.

Rank remaining rule candidates

In this step, the rule resolution algorithm uses a three-step sub-process to rank the remaining
candidate rules. First, the list of rule candidates is sorted. Then, all rule candidates marked as
Withdrawn are removed from the list. Finally, a default rule candidate is defined.

Sort the remaining rule candidates

The rule resolution algorithm sorts the remaining rule candidates according to this specific order:
Class, Ruleset, Circumstance, Circumstance Date, Date/Time Range, Ruleset, then Version.
The first two criteria — Class and Ruleset — provide the basics of rule resolution. The closer a rule
candidate is to the Apply to: class of the referenced rule, the higher the rule candidate is ranked.
Within each class, the rule candidates are sorted according to the operators' ruleset list.
Important: Rules which do not have the Use class-based inheritance to arrive at the correct rule to
execute check box selected in their class definition are not ranked by class.
The next three criteria — Circumstance (Property or Template), Circumstance Date, and Date/Time
Range — are used as qualifiers to the basics of rule resolution, and are used to further refine, or
specialize, rule candidates.
The last criteria — Version — ranks the remaining candidate rules by the ruleset version that contains
them. This ensures that circumstanced rules are not automatically overridden if the base rule is
updated in a more recent ruleset version.
Continuing with the example, the list of rule candidates is ranked according to class and ruleset order,
including any circumstanced rules, so no rules are removed from the list of rule candidates.

53
©2018 Pegasystems
 Apply to: class Rule Rule name Availability Ruleset Version Qualifier
type
TGB-Purchasing- Rule- CreateRequest Withdrawn Purchasing 02-01-10
Work- HTML-
PurchaseRequest Section
TGB-Purchasing- Rule- CreateRequest Available Purchasing 02-01-05
Work- HTML-
PurchaseRequest Section
TGB-Purchasing- Rule- CreateRequest Available Purchasing 02-01-01
Work- HTML-
PurchaseRequest Section
TGB-Purchasing- Rule- CreateRequest Available Purchasing 02-01-05 Yes
Work HTML- (Circumstance)
Section
TGB-Purchasing- Rule- CreateRequest Available Purchasing 02-01-05 Yes (Date)
Work HTML-
Section
TGB-Purchasing- Rule- CreateRequest Available Purchasing 02-01-05
Work HTML-
Section
TGB-Purchasing- Rule- CreateRequest Available Purchasing 02-01-01
Work HTML-
Section
TGB Rule- CreateRequest Available TGB 03-01-01
HTML-
Section

KNOWLEDGE CHECK

As candidate rules are ranked during rule resolution, which criteria is considered last? Why?
The version of the ruleset is considered last. This ensures that circumstanced rules are not
automatically overridden if the base rule is updated in a more recent ruleset version.

Remove rule candidates with an Availability set to Withdrawn

After the rule candidates are ranked, the rule resolution algorithm removes any rule candidates where
the Availability of the rule is set to Withdrawn.
When the Availability of a rule is set to Withdrawn, the rule is removed from the list of rule candidates.
Finally, all other rule candidates that match the Apply to: class, the ruleset name and major version

54
©2018 Pegasystems
number, the rule purpose, and any qualifiers of the rule set to Withdrawn are removed from the list as
well.
Continuing with the example, there is one rule candidate with an Availability set to Withdrawn.
Important: Notice all rules in the same Apply to class as the rule with the Availability set to Withdrawn
are removed from the list of candidate rules.
In this sub-step, three rules are removed from the list of candidate rules.
The rule candidate in TGB-Purchasing-Work-PurchaseRequest with the Availability set to Withdrawn is
removed. There are two rule candidates that match the Apply to: class, the ruleset name and major
version number, and the rule purpose of the Withdrawn rule, so they are also removed.

Apply to: class Rule Rule name Availability Ruleset Version Qualifier
type
TGB-Purchasing- Rule- CreateRequest Withdrawn Purchasing 02-01-10
Work- HTML-
PurchaseRequest Section
TGB-Purchasing- Rule- CreateRequest Available Purchasing 02-01-05
Work- HTML-
PurchaseRequest Section
TGB-Purchasing- Rule- CreateRequest Available Purchasing 02-01-01
Work- HTML-
PurchaseRequest Section
TGB-Purchasing- Rule- CreateRequest Available Purchasing 02-01-05 Yes
Work HTML- (Circumstance)
Section
TGB-Purchasing- Rule- CreateRequest Available Purchasing 02-01-05 Yes (Date)
Work HTML-
Section
TGB-Purchasing- Rule- CreateRequest Available Purchasing 02-01-05
Work HTML-
Section
TGB-Purchasing- Rule- CreateRequest Available Purchasing 02-01-01
Work HTML-
Section
TGB Rule- CreateRequest Available TGB 03-01-01
HTML-
Section

55
©2018 Pegasystems
Determine default rule candidate
The last sub-step in the ranking phase of the rule resolution algorithm determines the default rule
candidate.
A default rule candidate is the first rule candidate (highest ranked) that has no qualifiers. This default
rule candidate is the last possible rule to be executed as it always matches any additional requests for
this rule.
Additional rule candidates ranked below the default rule candidate are discarded.
Continuing with the example, the default rule candidate is TGB-Purchasing-Work-CreateRequest in the
Purchasing:02-01-05 ruleset.
The two rules below the default rule candidate are removed from the list of rule candidates.

Apply to: Rule Rule name Availability Ruleset Version Qualifier

class type
TGB- Rule- CreateRequest Available Purchasing 02-01-05 Yes
Purchasing- HTML- (Circumstance)
Work Section
TGB- Rule- CreateRequest Available Purchasing 02-01-05 Yes (Date)
Purchasing- HTML-
Work Section
TGB- Rule- CreateRequest Available Purchasing 02-01-05
Purchasing- HTML-
Work Section
TGB- Rule- CreateRequest Available Purchasing 02-01-01
Purchasing- HTML-
Work Section
TGB Rule- CreateRequest Available TGB 03-01-01
HTML-
Section

Set the rules cache

The rule resolution algorithm adds the remaining rule candidates to the rules cache.

Apply to: Rule Rule name Availability Ruleset Version Qualifier

class type
TGB- Rule- CreateRequest Available Purchasing 02-01-05 Yes
Purchasing- HTML- (Circumstance)
Work Section

56
©2018 Pegasystems
Apply to: Rule Rule name Availability Ruleset Version Qualifier
class type
TGB- Rule- CreateRequest Available Purchasing 02-01-05 Yes (Date)
Purchasing- HTML-
Work Section
TGB- Rule- CreateRequest Available Purchasing 02-01-05
Purchasing- HTML-
Work Section

57
©2018 Pegasystems
How to influence rule resolution through
rule availability
Rules that are subject to the rule resolution process have an Availability setting. A rule’s current
Availability is visible on the rule form next to the rule’s name or description.

The Availability setting is used to determine if a rule is available for use during rule resolution. The
availability of a rule is also used to determine if you can view, copy, or edit a rule in Designer Studio.
You can set the availability of a rule to one of five values.

Availability = Available
An availability of Available indicates the rule may be used during the rule resolution process.
Tip: When you create a rule, the default availability of the rule is set to Available.
You can view, copy, edit, and execute rules in Designer Studio when the availability is set to Available.

Availability = Final
An availability of Final indicates the rule may be used during the rule resolution process.
Rules marked as Final can be viewed and executed in Designer Studio, but cannot be edited or copied
into another ruleset.
Note: The Final setting is used by Pega to indicate Pega-provided rules that may be changed in
subsequent releases.

Availability = Not Available

An availability of Not Available indicates the rule may not be used during the rule resolution process.
When a rule set to Not Available is found during the rule resolution process, the rule in the next-
highest version is considered for rule resolution.
In the table below, the availability of the rule named CreateRequest in the Purchasing:02-01-10 ruleset is
set to Not Available. The rule in the next-highest version — Purchasing:02-01-05 — is considered for rule
resolution.

58
©2018 Pegasystems
 Apply to: class Rule type Rule name Availability Ruleset Version
TGB-Purchasing-Work- Rule-HTML- CreateRequest Not Available Purchasing 02-01-10
PurchaseRequest Section
TGB-Purchasing-Work- Rule-HTML- CreateRequest Available Purchasing 02-01-05
PurchaseRequest Section
TGB-Purchasing-Work- Rule-HTML- CreateRequest Available Purchasing 02-01-01
PurchaseRequest Section

Rules marked as Not Available can be viewed, copied, or edited in Designer Studio, but will not execute.
Tip: Set the availability of a rule to Not Available during initial development. This allows you to save a
rule without validation.

Availability = Blocked
An availability of Blocked indicates the rule may be used during the rule resolution process. If a
blocked rule is selected during rule resolution, execution is halted and an error message is displayed.
In the table below, the availability of the rule named CreateRequest in the Purchasing:02-01-10 ruleset is
set to Blocked. This version of the rule is available during rule resolution.

Apply to: class Rule type Rule name Availability Ruleset Version
TGB-Purchasing-Work- Rule-HTML- CreateRequest Blocked Purchasing 02-01-10
PurchaseRequest Section
TGB-Purchasing-Work- Rule-HTML- CreateRequest Available Purchasing 02-01-05
PurchaseRequest Section
TGB-Purchasing-Work- Rule-HTML- CreateRequest Available Purchasing 02-01-01
PurchaseRequest Section

Block a rule when access to the rule must be blocked immediately and you need more time to develop
and release an updated rule.
Rules marked as Blocked can be viewed, copied, or edited in Designer Studio, but will not execute.

Availability = Withdrawn
An availability of Withdrawn indicates all rules with the same purpose, Apply to: class, and in the same
ruleset are not considered during the rule resolution process.
When a rule marked as Withdrawn is found during rule resolution, the system looks for an instance of
the rule in the next highest class or ruleset.
In the table below, the availability of the rule named CreateRequest in the Purchasing:02-01-10 ruleset is
set to Withdrawn. All rules with same purpose, the same Apply to: class, and in the same ruleset are not
considered during rule resolution.

59
©2018 Pegasystems
 Apply to: class Rule type Rule name Availability Ruleset Version
TGB-Purchasing-Work- Rule-HTML- CreateRequest Withdrawn Purchasing 02-01-10
PurchaseRequest Section
TGB-Purchasing-Work- Rule-HTML- CreateRequest Available Purchasing 02-01-05
PurchaseRequest Section
TGB-Purchasing-Work- Rule-HTML- CreateRequest Available Purchasing 02-01-01
PurchaseRequest Section
TGB-Purchasing-Work Rule-HTML- CreateRequest Available Purchasing 02-01-05
Section
TGB-Purchasing-Work Rule-HTML- CreateRequest Available Purchasing 02-01-05
Section
TGB-Purchasing-Work Rule-HTML- CreateRequest Available Purchasing 02-01-05
Section
TGB-Purchasing-Work Rule-HTML- CreateRequest Available Purchasing 02-01-01
Section
TGB Rule-HTML- CreateRequest Available TGB 03-01-01
Section

Rules marked as Withdrawn can be viewed, copied, or edited in Designer Studio, but will not execute.

60
©2018 Pegasystems
 Parameterizing rules for reuse
Introduction to parameterizing rules for
reuse
In this lesson, you learn how parameters can help promote rule reuse and make your application
easier to maintain.
After this lesson, you should be able to:
l Describe the importance of creating modular, reusable rules
l Explain how parameters make a rule more reusable
l Add parameters to a rule to improve reusability

61
©2018 Pegasystems
Parameters
Parameters enable you to create generic rules that can be reused in more than one context.
For example, a list of available healthcare plans are stored in a single database table.

PlanName Type Description

Plan One Medical Lorem ipsum dolor sit amet, consectetur
adipiscing elit. Nunc eleifend orci urna, vitae
dapibus mi placerat quis.
Plan Two Medical Ut quis nulla eu neque sollicitudin molestie.
Mauris semper tortor non libero euismod, ac
volutpat dui rutrum
Plan Three Medical Duis sit amet nisl sed dui molestie cursus eu id
odio. Suspendisse scelerisque nunc vel risus
feugiat.
Plan Four Medical Nullam in posuere nibh. Nullam sit amet convallis
eros, eu ultrices sapien.
Plan Alpha Dental Maecenas gravida est purus, eget tincidunt enim
imperdiet at. Pellentesque a malesuada lorem, vel
vulputate nunc.
Plan Bravo Dental Curabitur sollicitudin, justo a gravida fringilla,
lectus leo tempor lectus, a aliquet arcu lectus
finibus magna.
20/20 Vision Pellentesque eget fermentum diam, nec convallis
nisl. Ut quis nulla eu neque sollicitudin molestie.
20/100 Vision Fusce non nisi egestas, pulvinar felis a, aliquet
arcu. Maecenas at lectus posuere, auctor odio sed,
dictum arcu.

Retrieving a list of available plans for a specific plan type requires a report definition with a filter
condition set to the specific plan type.

62
©2018 Pegasystems
If you hard code the value of the filter condition in a report definition, you must create a separate
report definition for each additional plan type. If additional plan types are added, you must create
additional report definitions for each new plan type. As the number of report definitions increases,
implementing changes becomes more time consuming and the risk of introducing an error increases.
KNOWLEDGE CHECK

State two disadvantages of creating a unique rule for each business context.
Implementing changes takes more time and the risk of introducing errors increases.

Create reusable rules with parameters

Parameters eliminate the need for a unique rule for each condition, or context. A parameter is a value
passed into a rule to make it more reusable.

63
©2018 Pegasystems
In the healthcare plans example, using a parameter to set the filter condition enables you to use a
single report definition to retrieve a separate list for each specific plan type.
Parameters enable you to separate the functional behavior of a rule from specific business contexts,
and therefore, maximize the reuse of the rule. Implementing changes takes less time and, because
only one report definition must be maintained, the risk of introducing errors is diminished.
KNOWLEDGE CHECK

State two advantages of separating the functional behavior of a rule from the business
context.
Implementing changes takes less time and the risk of introducing errors is diminished.

64
©2018 Pegasystems
How to make rules reusable with parameters
Rules that accept parameters have a Parameters tab where you specify the parameters the system
uses when the rule is executed. After the parameters are added, you can reference them in a rule,
including the rule in which the parameter is defined.

Define a parameter for a rule

Common fields
Each parameter consists of three common fields — Name, Description, and Data type.
Note: The Name and Data type fields are always required.
Name
Enter a unique name that clearly identifies the parameter. For example, to add a parameter for a tax
rate, use TaxRate. Do not use Rate, as it may be ambiguous to other architects.
The name should begin with a letter and can include letters, numbers, hyphens, and underscore
characters. When defining parameter names, follow your organization's naming convention for
properties.
Description
Provide a short description that describes how the parameter is used. For example, use Regional tax
rate used to calculate total order price.
Data type
Select the expected data type of the parameter's value.
Pega 7 performs a level of type-checking when you save a rule that references the rule on which the
parameter is defined, not at run time.

Additional fields
Additional fields — Required, In/Out, Default value, Smartprompt type, and Validate as — are available
for certain rule types.
Required
Use this field to indicate the parameter must have a value when the rule is executed.
You must select an option when the Required field is displayed. When Required is set to Yes, the
restriction is enforced when you save a rule that references the rule on which the parameter is
defined, not at run time.
In/Out
Use this field to indicate whether the parameter is used for input to the rule, or returned as output
from the rule.
The In/Out field is required when displayed. The In option is selected by default.
Default value
Use this field to define a literal constant value that appears as the default parameter value when
the system presents a parameter prompt dialog for this rule.

65
©2018 Pegasystems
 Smartprompt type
Use this field to configure a list of values to choose from when setting the parameter's value in
other rules.
Validate as
Use this field to identify a property for the Smartprompt Type operation.

Parameter pages
Each parameter you add to a rule is added to a parameter page. The parameter page stores values for
each parameter defined for a rule. Pega maintains a parameter page in memory for each parametrized
rule. The parameter page for a rule cannot be viewed using the Clipboard tool. To view the contents of
the parameter page, you use the Tracer to record execution of the rule, then view the contents of the
parameter page for the appropriate step in the Tracer results.

66
©2018 Pegasystems
How to pass a parameter value to a rule
Parameters can be referenced from any rule, including the rule in which they are defined. Depending
on where a parameter is defined — in the same rule, or in another rule — determines how it is
referenced.

Reference a parameter in a rule

To reference a parameter in the rule in which the parameter is defined, use the keyword Param in
front of the parameter name. For example, to add a filter to a report definition using a parameter
named PlanType, enter Param.PlanType in the Value field for the filter condition. When running the
report, Pega looks for the value of the PlanType parameter on the parameter page for the report
definition, and applies the value to the filter condition.

In the example above, two parameters (PlanType and PlanName) are defined on the Parameters tab of
the report definition. Use the keyword Param to access a list of available parameters, then select the
desired parameter.

Provide a value for the parameter

When you reference a parametrized rule, Pega prompts you with the name of each parameter
accepted by the rule. For each parameter, Pega provides a field in which to enter a value. This value
can be a constant, a property reference, or another parameter. When an application uses a
parametrized rule, Pega passes the value to the rule, and the parametrized rule returns the
appropriate result.

67
©2018 Pegasystems
In the example above, the data page references a report definition that has defined two required
parameters. The Parameters link on the data page rule opens a modal dialog that displays a list of
parameters defined in the report definition.
Note: If a referenced rule requires a parameter, the referencing rule indicates the required parameter
with an asterisk (*).

Pass a parameter page

Pega provides two options for passing parameters to a rule. By default, when you select a parametrized
rule, Pega lists each parameter accepted by the rule and provides a field for you to enter a value for
each parameter. You can also pass the entire parameter page for the current rule to the parametrized
rule by selecting the Pass current parameter page option. In the previous example, you could select
Pass current parameter page to pass a value for the PlanType parameter from the data page to the
report definition.
When you pass a parameter page to a rule, the rule reads parameter values from the parameter page
associated with the calling rule. Updates to parametrized values are made on the parameter page,
which may affect the behavior of the calling rule.
KNOWLEDGE CHECK

What keyword do you use to reference parameters in the rule on which the parameters are
defined?
Param

68
©2018 Pegasystems
CASE DESIGN

69
©2018 Pegasystems
 Creating temporary cases
Introduction to Creating Temporary Cases
When starting a business process, an organization may want to defer recording the case in the
database. Starting a case as a temporary case allows you to defer saving the case until one or more
threshold conditions are met. If the temporary case is closed or resolved, no record of the case will
exist.
In this lesson, you learn how to configure a temporary case for processing. You also learn how to use a
SmartShape to persist data to the database.
After this lesson, you should be able to:
l Describe the purpose of a temporary case
l Explain when to create a temporary case
l Configure a case for temporary processing
l Persist a temporary case

70
©2018 Pegasystems
Temporary Cases
Temporary cases store data that is not stored in the Pega database. For example, consider a change of
address case for a customer service application. The customer service representative (CSR) checks the
user's current address in the database. If the address is up-to-date, no changes are necessary. This
address check is temporary.

Temporary cases are modeled in screen flows and regular flows. In this diagram, the temporary case is
resolved.

Persist the temporary case

Once a case meets the qualifying condition specified by the organization, the case is ready to be
recorded in the database for future reference. The recording of a case in the database is referred to as
persisting the case. For example, when the customer has a new address that does not match the
existing address, the CSR continues the update process. This is the point in the workflow where you as
a developer indicate where to persist the case in the database.
To make the case permanent, and continue to the next stage of the Update Address process, add a
Persist Case SmartShape to the workflow.

KNOWLEDGE CHECK

Temporary cases capture information that is ________________.

not stored in the database

71
©2018 Pegasystems
KNOWLEDGE CHECK

What happens when the case is persisted? 

When the case is persisted, updated data is stored in the database.

72
©2018 Pegasystems
Configuring temporary case processing
When a business user creates a temporary case, the system does not create a case instance in the
database (an object ID is not created). As the case is processed, data remains in memory but is not
committed to the database.
In your process, decide when to persist the case. To persist the case, add a Persist Case SmartShape to
the flow. When Pega encounters the Persist Case shape, Pega creates a case instance and commits the
case data to the database.
When adding the Persist Case shape to the case life cycle, consider the information that must be input
to qualify the case. Remember to add the Persist Case shape only after this information has been
added to the case. For example, if a case type provides the user with a wizard to select the type of bank
account to open, you only persist the case after the user selects the account type and is ready to open
an account.

Create a temporary case

Configure the starting flow for a case (pyStartCase) so that the case is created as a temporary case.
1. From the Cases Explorer, open the case type rule.
2. On the Processes tab, next to the pyStartCase field in the Starting processes section, click the
Crosshair icon to open the pyStartCase flow rule.

73
©2018 Pegasystems
 Note: When you create a case type, Pega automatically creates a starting flow for you, named
pyStartCase. This flow initializes the case, and then runs the first process in the first stage of the
case life cycle.
3. On the Process tab, select the Temporary object check box.

4. Click Save. When the user creates a case, it will be temporary.

Persist a temporary case

1. In the Case Designer, open the case type.
2. Identify the step in the starting workflow where the case will be persisted to the database.
3. After the +Step you have identified, add a new step and select More.

74
©2018 Pegasystems
4. In the dialog that appears beneath the new step, expand the Utilities section.
5. Select Persist Case. The Persist Case panel is displayed.
6. In the panel, click Select.

7. On the case life cycle header, click Save. The process now includes the Persist Case SmartShape. In
this example, it follows the Collect Work Sample assignment shape.

75
©2018 Pegasystems
When a case is submitted after the Collect Work Sample step, the case is persisted to the database.

76
©2018 Pegasystems
 Searching for duplicate cases
Introduction to searching for duplicate cases
In this lesson, you learn how to configure the duplicate case search feature to identify duplicate cases
in the system. This feature allows users to decide which case is redundant and should be removed
from the process.
After this lesson, you should be able to:
l Describe situations in which users might submit duplicate cases
l Describe the duplicate case search logic and how it identifies duplicate cases
l Configure a duplicate case search

77
©2018 Pegasystems
Duplicate cases
In many situations, a user may enter a case that has many of the same data values as another case
already in the system. Usually, matching data is not an issue. For instance, two purchase requests may
have the same request date, the same items, or the same customer name. However, if a specific
combination of data values match, the new case is possibly a duplicate case.
For example, a health care services application processes requests to authorize insurance coverage for
surgical procedures. A user enters a request for a specific surgeon to perform inpatient surgery on
May 1 to repair a torn tendon. Two days later, the patient's health care provider discovers that the
surgeon is not available on the specified date. The provider submits a new request for the same type
of surgery, the same surgeon, and the same procedure but for a procedure date of May 7. Because
three of the four data values — the surgeon, type of surgery, and procedure — match in both requests,
the second request is likely a duplicate. To avoid double-booking the procedure, the user should not
process the request with the incorrect date. In these situations, users need to identify duplicate cases
so that users can process the correct case.
Pega provides the duplicate case search process to help users identify and resolve duplicate cases.
This process is implemented in your case life cycle as a Duplicate Search step. When a case enters the
step, the system uses weighted conditions to compare specific properties or values with cases
already in the system. Each condition has a weight (between 1 and 100) to determine the condition's
relative importance when making the comparisons. The system adds up the weights of all the
conditions that evaluate to true. If the sum exceeds a specified threshold value, the system flags the
current case as a duplicate. The duplicate case search process then displays to the user the current
case and the matching case in the system. The user may select the unwanted duplicate and resolve it.
The case is not processed. Alternatively, the user may decide that the current case is not a duplicate
and choose to continue processing the case.
In the previous example, assume that you have given the surgery type, procedure, surgeon, and date a
weighted condition of 25 each. The system displays the second request as a duplicate because the
surgeon name, surgery type, and procedure match the values in an existing case. The total condition
value is 75, exceeding a matching threshold of 50. The user decides that the second request is valid
and resolves the original request as a duplicate.

78
©2018 Pegasystems
KNOWLEDGE CHECK

What does duplicate case search use to compare specific properties or values with cases
already in the system?
Duplicate case search uses weighted conditions. Each condition has a relative importance defined by
a weighting value.

79
©2018 Pegasystems
How to identify duplicate cases
There are two main steps to implementing duplicate case search. First, you configure the duplicate
case search logic by adding weighted conditions. You also add conditions that must match in order for
a case to be evaluated a possible duplicate. Then, you add a Duplicate Search step to your case
lifecycle. The Duplicate Search step runs the duplicate case search process when a case enters the
step. The associated process uses the duplicate case search logic to flag duplicates. The process also
provides a user interface allowing users to either resolve or process duplicates.

Configure the condition logic

On the Case Designer Settings tab, use the Track duplicates panel to configure the weighted and
must match conditions. When you create the conditions, the system creates the case match rule
named pyDefaultCaseMatch rule. The logic for tracking duplicate cases is implemented in the duplicate
case search process.

Add weighted conditions

Enter weighted conditions that the duplicate search case process uses to identify duplicates. In the two
Conditions fields, enter the property names or values in the current case you want to compare with
existing cases. You can enter the current case and existing case values in either column. In the field
containing the value for the current case, you must add the Primary keyword to the value. For example,
in the first field, enter Primary.FirstName, and in the first field, enter .FirstName. Select the appropriate
relational operator between the fields.
Specify a relative weight for each condition. In the Weight field, enter an integer value between 1 and
100. The higher the value is, the greater the effect this value has on flagging a duplicate case.
In the Case is a duplicate when sum>= field, specify a numerical value to set the duplicate case
threshold. The duplicate case logic sums the weights of matching conditions. The sum is tested against
the threshold value. When the total weights of matching conditions equals or exceeds this threshold,
the system flags the current case as a duplicate case.
The following image shows an example of weighted conditions in the Track duplicates settings panel.

80
©2018 Pegasystems
The weights and thresholds depend upon the specific requirements of your organization. If weights
are incorrectly assigned, a large number of cases may unnecessarily be flagged as duplicates.
For example, assume an insurance authorization for a surgical procedure uses procedure type,
surgeon name, procedure date, and procedure as your conditions. You have set the threshold to 50.
Because procedure types and procedures frequently match with existing cases, you do not give the
conditions high weights. In combination, they should not exceed the threshold. In contrast, you give
surgeon name and procedure date higher weights. A case is more likely to be a duplicate if either of
these conditions evaluate to true.
The following table is an example of how you might weight the conditions.

Condition values Condition weights

.SurgeonName 30
.ProcedureDate 30
.ProcedureType 20
.Procedure 20

Also consider adjusting the threshold value if too many or too few cases are being identified as
duplicates.
KNOWLEDGE CHECK

How do you identify a weighed condition value that is in the current case?
You add the keyword Primary to the value.

Add must match conditions

As a best practice, include one or more must match conditions. When the duplicate case search
process begins, it first evaluates the must match condition. If the condition evaluates to true, the

81
©2018 Pegasystems
current case is considered a potential duplicate. The process then evaluates the weighted conditions.
To create a must match condition, you enter a value to evaluate for potential duplicates. You then
specify an operation. In some cases, you also enter a filter value. For example, assume you only want to
evaluate cases where the patient ID in existing cases match the patient ID in the current case. You
enter the patient ID as the value and an operation of is same. If the patient IDs match, the process then
evaluates the weighted conditions. In another example, you can filter out resolved cases by entering
.pyStatusWork as a potential duplicate value, does not contain as the operation, and "Resolved" as the
filter value.
Exact match conditions limit the number of weighted condition evaluations. This can help reduce the
number of incorrectly tagged duplicates and can help enhance performance.
Important: Properties that are referenced by a must match condition must be exposed as columns in
the database.
KNOWLEDGE CHECK

How does the duplicate case search process use the weights in weighting conditions to flag
a duplicate case?
The process sums the weights of all the conditions that evaluate to true. If the sum is greater than a
threshold value, the process flags the current case as a duplicate.

Add the Duplicate Search step

You add the duplicate case search process by adding a Duplicate Search step in the case lifecycle. You
can add the step anywhere in the case lifecycle. Typically, you check for duplicates after initial
information about a case has been collected. For example, when processing a loan request, users first
collect the customer's personal information and loan information. You add a Duplicate Search step
after this information is collected. Duplicate Search can evaluate conditions such as customer name,
loan type, and loan amount.
Tip: On the case lifecycle, click +STEP > More > Utilities > Duplicate Search to add the step.
When Duplicate Search identifies a duplicate case, the system displays a user form that lists the
current case and the matching cases. The system prompts the user to either select a duplicate case
and resolve it, or to continue processing the current case. This standard flow action
pyDuplicateSearchCases uses properties such as case status, creation date, and match score to identify
each case. You can customize pyDuplicateSearchCases by adding property values that help users
identify and resolve the correct duplicate. For example, you may add work party and email address.
KNOWLEDGE CHECK

Where in a process are you most likely to place a Duplicate Cases step?
Place the step after basic case information is collected.

82
©2018 Pegasystems
Combining temporary cases with duplicate cases
In some situations, duplicate cases can commonly occur due to high intake volume. For example,
assume that your application has a process for updating customer information. Because multiple users
enter updates, duplicate cases often occur. To prevent large numbers of unprocessed cases from
accumulating in the system, consider using temporary cases in the process. In this scenario, you would
set up the address update case type to instantiate temporary cases. You would then add the Persist
Case step after the Duplicate Search step. New cases that are not duplicates are persisted as they
advance through the process. If a new case is flagged as a potential duplicate, the case is not written to
the database if the user resolves it as a duplicate.

Configuring duplicate case search

For instructions on how to configure the duplicate case search feature, see the Help topic Tracking
duplicate cases.

83
©2018 Pegasystems
DATA MODEL DESIGN

84
©2018 Pegasystems
Configuring a localizable list of values
Introduction to configuring a localized list of
data values
In this lesson, you learn how to use field value rules to define items in a selection list presented to end
users. This enables you to restrict the values of a property to one of a fixed list of choices.
After this lesson, you should be able to:
l Describe how field values are used to define allowed data for properties
l Configure a field value rule
l Add a list of field values to a property rule

85
©2018 Pegasystems
Field values
When building an application, you often need to use a list of allowed values for a specific property. If
the list of allowed values is short, mostly static, and common, for all case types in the application, the
list of allowed values may be defined in a local list on the property record.
If the list of allowed values is large, expected to change frequently, or may be specific for each case
type, you can use a field value.
Field values provide an alternate method for defining allowed values for properties. Field values
enable you to manage the list of allowed values separately from the property. Managing the allowed
values separately from the property enables you to reuse a single property, and customize the allowed
values based on the context of the property.
For example, in a Pega 7 application, every case instance has a status, which changes as the case
progresses through the case life cycle. The status of a case is set using the property named
.pyStatusWork. The list of allowed values for setting .pyStatusWork is defined using field values.
You can add different field values for a single property in the same context, or in separate contexts
using the Apply to: class setting for each value. You can also use rulesets to maintain different versions
of each field value in each context.

Applies To Field Name Field Value Ruleset:Version

Work- pyStatusWork Open Pega-ProCom:07-10-01
Work- pyStatusWork Pending Pega-ProCom:07-10-25
Work- pyStatusWork Resolved-Completed Pega-ProCom:07-10-25
TGB-HRApps-Work-Candidate pyStatusWork Open-Scheduling HRApps:01-01-01
TGB-HRApps-Work-Onboarding pyStatusWork Open-Enrollment HRApps:01-01-01
TGB-HRApps-Work-Onboarding pyStatusWork Pending-Enrollment HRApps:01-01-02

In the table above, the Pega-provided property used to set the status of a case — .pyStatusWork — uses
a common set of allowed values as defined in the Work- context. This common set of allowed values is
available for all applications built on the Pega platform.
Additional custom values are defined for the HRApps application. These values are usable in the TGB-
HRApps-Work-Candidate and the TGB-HRApps-Work-Onboarding contexts (case types).
Field values also support localization of words, phrases, and sentences that appear on portal displays,
reports, and user forms.
KNOWLEDGE CHECK

A field value enables you to manage the ________________ separately from the ______________.
list of allowed values, property.

KNOWLEDGE CHECK

86
©2018 Pegasystems
 True or False: You can add different field values for a single property in the same context.
True

87
©2018 Pegasystems
How to configure field values
You can create field values to restrict the values of a property to a list of allowed values.
First, organize a list of allowed values you want to display in the list for the property. Next, create a
Field Value record for each allowed value. In the record, enter the value you want to display. Then,
identify the appropriate Apply to: class of the property where you want to display the list. Finally,
associate each Field Value record to the property where you want to display the allowed value.

Identify the values you want use

Use values that are meaningful to the user so the purpose of each value in the list is clear. For
example, to prepare a list of values used to select a state or territory, use standard abbreviations or the
full name of each state or territory (TX or Texas; KA or Karnataka; AA or Alsace).

Create a Field Value record for each allowed value

Create a new Field Value record for each allowed value.

In the Label field, enter one of the allowed values you organized.
In the Apply to: field, select the class where you want to apply the allowed value.
In the Field Name field, select the property on which you want to display the allowed value.
The Help topic Field Values - Completing the Create, Save As, or Specialization form provides details
on how to create a field value record.

88
©2018 Pegasystems
Localizing field values
Field value records include a field for you to provide a label translation. To translate a field value, save
a copy of the field value record to a ruleset for localized rules and, in the To field, enter the translated
value for the label. The following example shows a field value configured to provide a translation of the
label "Facilities" into French.

When a user in a French locale accesses the field value record, Pega automatically uses the version
from the localized ruleset.
For more information on localizing labels and list values with a field value record, see the Help topic
Field Value form - Completing the Localized Label tab.

89
©2018 Pegasystems
 Configuring data access patterns
Introduction to configuring data access
patterns
Pega includes powerful data capabilities to improve the speed and quality of development.
This lesson introduces data access patterns — these are used when creating the data model and
integration that support the Pega application. Patterns provide a common taxonomy for Pega solutions
promoting scalability and reuse. This lesson covers five data access patterns.
After this lesson, you should be able to:
l Describe the data access patterns available in Pega and their uses
l Configure a property to refer to a data page
l Configure a property to copy a data page
l Configure a data page with keyed access
l Reference a data page from a UI control
l Configure a reference property

90
©2018 Pegasystems
Data access patterns
Data access patterns provide simple mechanisms to help technical staff effectively manage data in a
Pega application. This section introduces five data access patterns that are available in Pega. These
patterns may be used as a starting place to create solutions for specific situations.
This section provides an overview of how each pattern may be tailored for a Pega application. The best
way to master these patterns is to experiment with them in different situations.

System of record pattern

The System of Record (SoR) pattern is used when a case needs access to data that is stored in another
system or application. The case does not own the reference data. Data is referenced as needed by the
application for context or to populate rules. For example, a loan application or credit card dispute
accesses customer account information and history.
Data loaded from the SoR pattern usually comes from an external data source. The SoR pattern helps
to ensure that data displayed in the Pega application is current. For example, if the account holder has
a new phone number, the updated number is displayed when the data is accessed from the case.

Snapshot pattern
The snapshot pattern copies data into the case. Once the data is copied into the case, the data is not
retrieved from the source again unless the request parameters change.
The snapshot pattern may be used to provide a copy of the data at a specific point in time. For
example, for an insurance claim, the snapshot pattern provides a copy of the policy data at the time
the claim is filed. If the policy changes after the claim, you do not want to update the policy data. This
is the opposite of the SoR pattern discussed earlier.

91
©2018 Pegasystems
Reference pattern
Reference data is a simple pattern used frequently in Pega applications. This pattern references data
that is usually not directly connected to a given case. Therefore, the data is not part of the data model.
Examples of data in a reference list include:
l Products
l Automobile makes and models
l Drop-down values (for example, countries and states)
The data can be used by multiple cases or applications. In many cases, the data is used to populate
user interface controls.

Keyed access pattern

The keyed access pattern is used to populate a list of objects and access information about a specific
object in the list. When retrieving a list of objects, the details for each object are retrieved as part of
the list. This eliminates the need for subsequent calls to retrieve object details.

The keyed access pattern is appropriate when users need to frequently switch back and forth between
objects in a large list, such as when loading a list of currencies and exchange rates.
When appropriately applied, the keyed access pattern significantly improves application performance
and maintainability.

92
©2018 Pegasystems
Alias pattern
The alias pattern links one property to another — it is an alias for a property.
For example, in an auto insurance quoting application is a data structure with two lists. One list
includes drivers on the auto insurance policy. The other list includes vehicles covered by the policy.
Each vehicle has a primary driver. Use the alias pattern to link each vehicle to a driver in the driver list.

The alias pattern prevents duplication of data, streamlines data management, reduces memory
footprint, and improves performance.

93
©2018 Pegasystems
How to configure the reference pattern
To implement the reference pattern, reference a data page directly in your application. For example, a
data page can be referenced in a drop-down control.

The data pages are used directly in the drop-down control and are not part of the data model. When
implementing the reference pattern, data pages are often node-level since the data is not linked to a
specific case and can be shared.
KNOWLEDGE CHECK

To implement the reference pattern, use a data page in your application without defining it
as part of the _______.
data model

94
©2018 Pegasystems
How to configure the SoR pattern by
referencing a data page from a property
If you need to reference the most current data in an external system, use the System of Record (SoR)
pattern. For example, use the SoR pattern if you are building a seating request application. Every time
the case is accessed, the user must see up-to-date information for the seating assignment transaction.
To implement the SoR pattern, you reference a data page from a property rule. The type of property
(page or page list) must correspond to the structure of the data page (page or list). A new data page is
created on the first reference to the property.

Data is not stored in the property that refers to the data page. The property only contains a reference
to a data page, as illustrated in the following screenshot of the clipboard.

95
©2018 Pegasystems
Reloading the data
The data reloads according to the refresh strategy specified on the data page. The property always
points to the current version of the data page.
Whenever a data page parameter is updated, a new data page is created. The property then points to
the new page.
KNOWLEDGE CHECK

Data is, or is not, stored in the property that refers to the data page?
Is not

96
©2018 Pegasystems
How to configure the snapshot pattern by
copying data from a data page
If you want to populate a property with data from a specific point in time, use the snapshot data access
pattern. For example, you may opt to use a snapshot pattern for an insurance claim case. When the
business user creates a new insurance claim, the customer's insurance coverage information is copied
into the claim from an external system. Each time the case is opened, the insurance coverage
information recorded in the case remains unchanged.
To implement the snapshot pattern, use the Copy data from a data page option on a property. The
type of property (page or page list) must correspond to the structure of the data page (page or list).
The first time the property is referenced, the data page is created and the data is copied to the
property. You may also choose to specify a data transform for data mapping in Optional data
mapping.

When you copy data from a data page, the data is stored in the property. The data page is not accessed
again unless it has a parameter that changes. When the parameter changes, a new data page is
created. The impacted data is copied to the property and overwrites the existing data.
KNOWLEDGE CHECK

97
©2018 Pegasystems
 When you copy data from a data page, the data is refreshed only when _____________.
a data page parameter changes

98
©2018 Pegasystems
How to configure the keyed access pattern
using keyed data pages
The keyed access pattern serves as an alternative to having two separate data pages. Follow these
steps to configure keyed data pages:
1. Define the data page Structure as a List.
2. Select Access pages with user defined keys.
3. Select Allow multiple pages per key to filter a large list to create a smaller list.
4. Specify the Page list keys used to access the list entry.
In the following example, the currency code is defined as the key for a data page of currency
conversion rates.

If you use the data page without a key, all of the exchange rates are displayed, for example, in a drop-
down.
Note: There is no option to specify keys.

99
©2018 Pegasystems
Using the data page with a property allows you to specify keys. In this example, the application displays
the exchange rate for a specific currency if you provide a key.

100
©2018 Pegasystems
KNOWLEDGE CHECK

A keyed data page serves as an alternative to having ___________.

two separate data pages

101
©2018 Pegasystems
How to configure the alias pattern using
reference properties
Use reference properties to implement the alias patterns. On the property, select the Allow use as
reference property in activities option. Reference properties can reduce the need for data
duplication. They can also simplify lengthy property references. The setting can be found on the
Advanced tab of the property rule.

You need an activity to set up the property reference. Use the Property-Ref method to create the link
between the source and target properties. Once linked, the references are maintained until the link is
explicitly broken or changed using the Property-Ref method.
Note: Property references cannot be circular.
In this example, two embedded page lists are defined in the case type. One list includes drivers on the
policy. The other list includes vehicles covered by the policy. Each vehicle has a primary driver that
links to an entry in the list of drivers on the policy.

Insurance representatives need to see primary-driver details such as name and license number
together with vehicle data. Use reference properties to link the primary driver to an entry in the list of
drivers on the policy. Using reference properties, you can access driver details from the vehicle page
since the driver page appears as if it is part of the vehicle page.

102
©2018 Pegasystems
Use the Property-Ref activity method to set up the reference property.

On the clipboard is a reference from the PrimaryDriver page property to the driver page in the Drivers
page list property.

Reference properties are not common, but they can be powerful in more advanced data structures that
require linking of embedded entities. Reference properties can help improve run-time performance,
and make design time easier by making property references simpler and more intuitive.
KNOWLEDGE CHECK

A reference property links one property to ____________________.

another property

103
©2018 Pegasystems
PROCESS DESIGN

104
©2018 Pegasystems
 Creating organization records
Introduction to creating organization records
Pega 7 supports a three-level organizational structure. In this lesson, you learn how to use the
Organization Chart and organization records to modify the organizational structure. You also learn how
to use Dynamic Class Referencing (DCR) to reference objects in different classes.
After this lesson, you should be able to:
l Describe the relationships between parts of the organizational structure
l Differentiate between a work group and an organizational structure
l Modify an existing organizational structure
l Create a work group and a workbasket
l Describe Dynamic Class Referencing (DCR)
l Update a workbasket name using DCR

105
©2018 Pegasystems
Organization records
A Pega application uses an organizational structure to direct assignments to the right operator or
workbaskets, determine the access rights of operators, and report on activity in various company
departments. For example, in order to approve a home loan, the request has to move through different
levels in the organization, starting at the customer representative all the way to the approving
manager. The structure is built with standard data instances called organization records. You use
these rules to support your requirements, and you can find these rules in the Records Explorer in the
Organization category.
The Pega organizational structure is a three-level hierarchy. The top level is known as the
organization, the middle level contains divisions, and the lowest level contains organization units.
A hierarchy has only one organization, and this represents the entire enterprise. A company such as
Apple or IBM would map to an organization in the hierarchy. An organization can have one or more
divisions. A division can be defined as a layer for categorizing business units such as a region, a brand,
or a department. Divisions can have one or more units. A unit contains operators who perform work
specific to their organization. These operators can include caseworkers, agents, and customer service
representatives. A unit can have child units. For example, two units (such as Hardware and Software)
may report to a single unit (Internal) which belongs to the IT division. The Internal unit manages IT
requests from inside the organization. The child units handle the requests and inventories and ships
the items.
Note: A division cannot have subdivisions.
The following chart shows a sample organization and its hierarchy. The OurCo organization has three
divisions — Sales, IT, and HR. Each division has its own units. In this example, IT has two units named
Internal and Customer. The Internal unit has two units that report to it — Hardware and Software.

Note: The Pega designations of organization, division, or unit do not necessarily coincide with the
company’s official organizational chart. Instead, organization rules refer to the work that users do and
the levels of access they have in Pega applications.

106
©2018 Pegasystems
An operator is associated with a unit, division, and organization. The operator ID record (also an
organization rule) stores the operator's organizational structure. You can update the operator's
organization structure, if necessary.
A workbasket is an organization rule, but is not part of the organizational hierarchy. A workbasket
belongs to a unit, a division, and an organization. By default, an operator can access work in the
workbasket to which the operator belongs.
Note: A workbasket is sometimes referred to as work queue because it provides a queue of open
assignments available to multiple operators. For more information, see the Help topic Routing an
assignment to a work queue.
You can use the organization structure in various ways:
l You can define access groups available to operators at the organization or division levels. These
access groups apply only if operators do not have an access group defined in their operator ID
record.
l You can configure routers that send assignments to operators or workbaskets defined within the
organizational structure.
l You can use manager data associated with the organization records in routing configurations,
approval processes, and SLAs. For example, an operator ID lists a manager the operator reports to,
and a unit record specifies a unit manager. The operator's manager can report to the unit manager.
For example, you can route a purchase request to a manager if the amount is up to USD10,000. If
the amount exceeds USD10,000, you can route the request to a unit manager.
l You can configure SLA configurations. Since each assignment contains the organizational data of
the assigned operator, you can use the data to determine escalation actions to specific managers.
For instance, if a purchase request is past goal, the case is escalated to the operator's manager. If
the case is past deadline, the case is escalated to the unit manager.
KNOWLEDGE CHECK

When you associate an operator with an organization hierarchy, which rules do you use?
Organization, Division, and Unit

107
©2018 Pegasystems
Work groups
A work group identifies a cross-functional team that contains a manager, and a set of operators, a set
of workbaskets, or both. You create work groups so that resources can be shared among units,
divisions, or the entire organization. Even though operators and workbaskets belong to a unit,
associating an operator with a work group allows the operator to share work with another operator in
other units. In the following example, the Onboarding work group is associated with the Human
Resources (HR) unit and Training unit. Because each unit has its own default workbasket, the work
group contains both workbaskets. Operators in the HR unit and Training unit are associated with the
work group and share work. One operator in the Accounting work group is also associated with the
Onboarding work group. This allows the operator to share work with the other operators in the
Onboarding work group.

A work group is an organization rule but not a level of the three-level hierarchy. An operator must be
associated with at least one work group and can belong to more than one work group. A work group
contains one workbasket.
A work group instance identifies one user who is the work group manager. The system can use
manager information in a work group for notification tasks and routing tasks. Work groups give
managers the flexibility to assign, monitor, and report on work performed in each work group.
Managers use the Case Manager portal to access the work being performed in work groups. The Case
Manager portal refers to work groups as teams. The following image shows work groups displayed as
Teams in the Case Manager portal.

108
©2018 Pegasystems
Teams contain operators. In the Case manager portal and in work queues, operators are referred to as
Members. The portal allows managers to drill down and monitor work for each team member and
workbaskets in a team. For instance, a manager can select a member's icon to open the member's
worklist. If the member belongs to more than one team, the manager can see the items the member is
working on in all the teams. The manager can also add or delete operators and workbaskets in the
Members and Work queues sections, respectively.

109
©2018 Pegasystems
KNOWLEDGE CHECK

Which of the following is not part of the organizational structure: Division, unit, work group,
or organization?
A work group is not part of the organizational structure. Although it is an organization rule, a work
group is used to allow managers to monitor, report, and assign work among operators and
workbaskets across the organization.

110
©2018 Pegasystems
How to update an organizational structure
As companies grow, system architects may extend the existing organizational structure to reflect
organizational change. You may have to add new organization levels, work groups, and workbaskets.
You associate operators with an organization structure in order to define how work is routed to the
operator.
When you create a new application using the New Application wizard, you specify an organization.
Pega provides a default division and unit for that organization. For example, if you enter TGB as the
organization, the system creates a division named Div and a unit named Unit. You have the option to
name the division and unit you want in your new organization.
The example in this topic assumes that an organization has a Human Resources (HR) unit. Due to
business expansion, the company intends to add a unit named Benefits that reports to an HR unit.
Operators belonging to the unit will also be in a new work group that contains a new workbasket.
Follow these steps to update the organization in this example:
1. Add a new unit to the hierarchy.
2. Create a new work group.
3. Create a new workbasket.
4. Associate the workbasket with the work group.
5. Associate the unit and work group with an operator.
Important: Because of mutual dependencies, a workbasket or a work group must already exist before
either instance can be created. You cannot create both the workbasket and the work group at the
same time. For example, when you create a new work group, you must use an existing workbasket —
this is required value. After you create a new workbasket, go back to the work group and update the
workbasket.
The following image shows the sequence of steps using the previous example.

111
©2018 Pegasystems
Note: You can create new organization records such as units, work groups, and workbaskets from the
Records Explorer. In the Organization category, select a rule type, right-click, and click +Create.

Adding a level to the organization hierarchy

Use the chart on the Organizational Chart landing page to add levels to an organization. The chart
helps you see where in the hierarchy you are adding a level. From the Designer Studio menu, select
Org & Security > Organization > Organizational Chart to open the landing page. You can also
access organizational charts on the Chart tab on Organization, Division, and Unit records.
To add a layer, select an entry in the organizational hierarchy. Right-click to display a menu that lets
you add organizations, divisions, and units. Organization names are unique and cannot be used in
more than one hierarchy. For example, a division cannot belong to more than one organization, or a
unit cannot belong to more than one division.

112
©2018 Pegasystems
In this example, a subunit named Benefits has been added to its parent unit, HR.

For more information on how to use the chart, see the Help topic Organizational Chart.

Adding a work group

From the Records Explorer, create a work group record. By convention, end the work group name with
an at sign (@) and an organization name, such as Benefits@TGB. In the Manager field, enter a work
group manager for reporting and routing purposes. In the Default workbasket field, select a
workbasket. The standard router activity ToDefaultWorkbasket uses this value to locate a workbasket,
based on the work group associated with the current operator. For example, you can enter the default
organization workbasket such as default@TGB. After you create a new workbasket for the work group,
you update this default workbasket with the new one.

113
©2018 Pegasystems
Save the work group record but leave it open. Next, enter the name of the new workbasket in the
Default workbasket field. To help users and developers easily distinguish workbasket and operator
identifiers, choose a naming convention specifically for workbaskets. For example, include WB as a part
of the name as shown in the following example. Then, click the Crosshair icon to open a Create
Workbasket form.

Adding a workbasket
Complete the New Workbasket form and create the record. In the Organization section on the
workbasket form, first select the organization in the Name field, and then complete the Division and
Unit fields. In the Work group field, enter the name of a work group that uses this workbasket. This
field determines which workbaskets appear in a Team's Work Queues list on the Manager portal. Save
the record to associate the workbasket with the work group.

Return to the open work group record and save it. The workbasket you created is now the work group's
default workbasket.

Update the operator record

Open an operator record that you want to associate with the new level. On the Work tab, update the
Organization unit values. Then, in the Work group field, select the work group you want to associate
with the operator. Finally, add the work group to the Workbasket field.

114
©2018 Pegasystems
KNOWLEDGE CHECK

A requirement states that you must add a new division to your organization. What approach
allows you to see where in the organization hierarchy you are adding the division?
Select the organization in the organization chart and use the chart menu to add the division.

115
©2018 Pegasystems
Creating a work group and a workbasket
A workbasket must be associated with a work group. Similarly, a work group must be associated with a
workbasket. In some situations, you must create both a new workbasket and work group that are
associated with each other. Follow these steps to create a work group and a workbasket, and then
associate the workbasket with the work group.
1. In the Records Explorer, select Organization > Work Group and click +Create to display the Create
Work Group form.
2. In the Short description field, enter a description.
3. In the Work Group Name field, enter a work group name. Remember to use the standard naming
convention by adding an at symbol (@) and the organization name. In the following example, the
Work Group name is Benefits@TGB.

4. Click Create and Open.

5. In the Manager field, on the Work group tab, in the Work Group form, select a work group
manager.
6. In the Default workbasket field, select a default workbasket. In the following example, the
workbasket is the default for the organization, default@TGB.

7. Click Save to create the new work group.

8. In the Default workbasket field, in the Work Group form, overwrite the value with the name of the
new workbasket. Use a naming convention that indicates the record is a workbasket. In the following

116
©2018 Pegasystems
 example, the new workbasket is BenefitsWB. Later, you will enter this name in the Create
Workbasket form.

9. Click the Crosshair icon to open the Create Workbasket form.

10. In the Short description field, enter a description.
11. In the Workbasket field, enter the name you entered in the Work Group form.

12. Click Create and Open.

13. On the Workbasket form, on the Workbasket tab, select the required organization levels in the
Name, Division, and Unit fields.

117
©2018 Pegasystems
14. In the Work group field, select the work group you created.

15. Click Save to create the new workbasket.

16. Return to the Work Group record and click Save to associate the new workbasket with the work
group.

118
©2018 Pegasystems
How to customize reusable processes with
Dynamic Class Referencing
Many framework properties and data instances are meant to be reused without modification in the
implementation layer. For example, a process for approving a loan request in the framework layer may
be reused as-is without having to copy the process into your implementation layer.
However, you may have to make minor modifications. For example, you may want to use a workbasket
defined in your implementation, not in the framework, for routing assignments. If the framework is
locked, you have to copy the entire process to make the update.
Copying from the framework to the implementation layer can increase rule maintenance costs.
Whenever framework rules are updated, you must update the copy in your implementation. This
process can be especially time-consuming with multiple implementations.
Dynamic class referencing (DCR) is a Pega design pattern that enables you to easily reuse framework
rules without having to copy the rules into implementation layers. DCR uses a data page in the
framework layer that holds properties typically sourced from the data transform. In your framework,
you configure rules that reference the data page property. In your implementation, you specify the
data page and the property you want.
DCR is especially useful when you make small modifications to implementation rules you are reusing.
In the following example, the only differences between the processes is that the assignments use
different workbaskets in their routers. You can use DCR to reference the workbasket property in the
data page. This means that you do not have to copy the flow rule and manually update the workbasket
value in the router. Using DCR, the system runs the framework flow and references the workbasket
used in the implementation class.

119
©2018 Pegasystems
The use of dynamic referencing is not limited to frameworks. You can configure the DCR data page and
data transform in the implementation layer. For instance, a claims application can process both home
and auto insurance claims. Some of the flows can be reused as-is for both claim types. The flows are
located in the class group.
However, each claim type may require minor customization. For example, you may have a step in which
cases are routed to a workbasket. The workbaskets in each case type differ depending on the claim
type or other parameters, such as the organizational unit. You can configure DCR in each case type to
handle the differences. When you use this approach, you do not have to specialize the flows in each
case type.
KNOWLEDGE CHECK

You want to promote reuse of framework assets using DCR. Where would you put the
required extension properties?
In the framework layer

Configuring DCR
When you configure a framework DCR, you first create a data class in the framework that contains the
properties used as the dynamic reference variables. This approach lets you easily find the extension
points that need to be configured when extending the framework. In the following example, the Ins-
FW-ClaimsFW-Data-AppExtension data class contains a property (.ManagerWB) that is used as a
variable.

You then create a page property in the framework class group. This approach makes the property
available to all application layers. In the following illustration, the page property, AppExtension, is in
class group Ins-FW-ClaimFW-Work. The value in the Page Definition field is the data class holding the
property. The Data access section refers to a data page holding the extension values. In this example,
the data page is named D_AppExtension.

120
©2018 Pegasystems
In the data page holding the extension values, you specify the data source. You typically use a data
transform as the data source. You can alternately use other data sources such as the results of
decision rules or declare expressions. For example, you can use a decision table to determine the
correct property based on an organization unit. In the following example, the data page is sourced
from a data transform.

121
©2018 Pegasystems
The data transform is in the framework data class but is overridden in each application ruleset. You set
the target to the variable property defined in the framework data class. In this example, the target is
.ManagerWB.

122
©2018 Pegasystems
When you reference the target property, you first specify the framework data class and then the
property. In the following example, the assignment is routed to .ManagerWB in the framework data
class .AppExtension.

At run time, the process uses the data page value on the clipboard and routes the assignment to the
workbasket specified in the implementation layer instead of the workbasket specified in the framework
layer.

123
©2018 Pegasystems
 Configuring a cascading approval
process
Introduction to configuring a cascading
approval process
Pega provides the ability to include single and cascading approvals when designing case types. This
lesson focuses on how to convert a single approval to a cascading approval.
After this lesson, you should be able to:
l Differentiate a cascading approval from a single approval
l Identify the appropriate cascading approval model
l Configure a cascading approval process

124
©2018 Pegasystems
Cascading approval
Approvals vary depending on the case type. An application for auto insurance may need one approval
from the company underwriter. Some case types, such as a purchase request or an expense report,
may need a series of approvals. A cascading approval process configures a series of approvals.
The two cascading approval models are reporting structure and authority matrix.
The reporting structure model works when approvals always move up the submitter's reporting
structure or another defined list.
The authority matrix model works when the approval chain is directed by a set of rules to individuals
both in and out of the submitter's organization.
To determine which model to use, write the requirement in a simple sentence, beginning the sentence
with "When". Following are examples for each approval model.

Reporting structure example

When an employee submits a purchase request, the employee's direct manager must approve the
request. Amounts over USD500 require more approvals from people above the manager.

125
©2018 Pegasystems
The purchase request example contains no conditions. Every time an employee submits a purchase
request, the request must be approved by a defined list of approvers. When there are no conditions,
use the reporting structure model.

Authority matrix example

When an instructor submits an expense report, if a line item is billable to a customer, then accounts
payable must approve the line item.

The expense report example contains a condition. If an expense item is billable, then accounts payable
must approve the expense item. When conditions exist, use the authority matrix model.
KNOWLEDGE CHECK

What is the difference between the authority matrix and reporting structure cascading
approval models?
The authority matrix model works best when the approval chain is directed by a set of rules to
individuals both in and out of the submitter's organization. The reporting structure model works best
when approvals always move up a defined list.

126
©2018 Pegasystems
How to configure cascading approval
When an application requires multiple approvals of a case based upon specific criteria, you add a
cascading approval step in your case life cycle.
Consider a requirement for approvals of a purchase order based on the value of the order.

Purchase request value up to Approval requirement

USD25,000 Cost Center Manager
USD75,000 Vice President
USD100,000 Vice President of Finance
USD500,000 Senior Vice President
over USD500,000 Chief Financial Officer

You use the criteria in the table to configure a process for routing a case through multiple approvals.
For example, the Cost Center Manager, the Department VP, VP of Finance, and Senior VP must approve
a USD110,000 purchase request.
The approvals proceed sequentially through the hierarchy. For instance, after the Cost Center Manager
approves the request, the case is routed to the Vice President.
To configure a cascading link to configuring a decision table.approval step, you first add an approval
step to a stage. Then, you specify Cascading as the approval type. Finally, you choose the approval
model: a reporting structure or an authority matrix.
Note: You can also configure a cascading approval in a process flow by selecting the Cascading
Approval Smart Shape from the Smart Shapes menu in the process modeler.

Reporting structure
The Reporting structure has two default single-level modes for routing an approval — either the
submitter's reporting manager or work group manager. The manager information is defined in each
submitter's operator ID and associated work group. If the operator ID lists more than one work group,
Pega uses the default work group to determine the work group manager.
You can assign levels of approval to route cases up the organization's management hierarchy:
l One — This is either the reporting manager or the work group manager you specified.
l All — This is the submitter's entire manager hierarchy.
l Custom — This is a specified number of levels as determined by the evaluation of when rules.
Specify a manager at each approval level and define a cut off with a when rule for each manager.
The following example shows a cascading approval configuration based on the reporting structure,
with two when rules used to determine the number of approvals needed.

127
©2018 Pegasystems
Authority matrix
The authority matrix model determines the approvers using a list of operators stored in a Page List and
a single value property that identifies the approver. In most situations, you use a decision table to
define conditions for populating the list. When a request is made, the system populates the approver
list with the operators who evaluate to true in the table. The following image shows an example of a
cascading approval based on an authority matrix.

For instructions on configuring a decision table, see the Help topic About Decision Tables.
KNOWLEDGE CHECK

128
©2018 Pegasystems
 What is the purpose of a cascading approval step?
A cascading approval step simplifies the configuration of a process that requires multiple approvals.
You can base the cascading approval on a reporting structure or on an authority matrix.

129
©2018 Pegasystems
Configuring cascading approval
When configuring a process that requires multiple approvals, you use a cascading approval step.

Prerequisites to configuring a cascading approval

Prior to configuring a cascading approval, determine the cascading approval model (reporting
structure or authority matrix) to implement and identify the approval criteria.
If you choose the reporting structure model, determine the required number of approval levels. If the
number of levels varies based on case data, such as the amount of a purchase request, configure when
rules to test the threshold for each approval level.
If you choose the authority matrix model:
l Configure a page list property to hold the list of approvers.
l Configure a single-value property as an element of the page list to identify each approver in the list.
l Optionally, configure a decision table to determine the conditions for populating the page list. For
example, you can use the property .ApproverID to identify the approver for each cost level.

Important: When using a decision table with an authority matrix, set the decision table to Evaluate
all rows to return a list of results. Otherwise, the decision table returns only one result.
l If you do not use a decision table, configure a data transform or activity for populating the list if the
approvers are the same under all conditions.
Tip: Configure the authority matrix using a decision table if you intend to delegate control of the
authority matrix to business users.
See the PDN article Route cases for approval with the Cascading Approval Smart Shape for
instructions on configuring properties and a decision table for an authority matrix, and configuring
levels of approval for a reporting structure. Note that some descriptions of the Case Designer are out-
of-date.

Configure the cascading approval

To add a cascading approval step to your case life cycle, do the following:

130
©2018 Pegasystems
1. On the Life cycle tab of Case Designer, hover over a process and click + Step.
2. In the palette that is displayed, click Approve/Reject.
Caution: The system adds an alternate stage named Approval Rejection to your case type. Do not
delete or rename this stage because users will not be able to reject cases.
3. In the text field that is displayed, enter a unique name that describes the step.
4. On the step panel's General tab, select Cascading in the Approval flow type field.
5. Refer to the help topic Configuring approval shape options for instructions on how to configure the
approval models. For reporting structure, see the topic section: To use a reporting structure. For
authority matrix, see the topic section: To use a list of reviewers.

131
©2018 Pegasystems
 Prioritizing user assignments
Introduction to prioritizing user assignments
Cases consist of a series of tasks, often assigned to users. Users must perform the most important work
first, and only perform assignments appropriate for their skill set. System architects can configure
applications to select user assignments, matching each user with an appropriate assignment.
After this lesson, you should be able to:
l Explain the user-selected assignment model
l Explain the system-selected assignment model
l Prioritize assignments using Get Next Work

132
©2018 Pegasystems
Assignment models: user- and system-
selected
With Pega, end users can choose what to work on next by selecting an item from a worklist. For
example, a case worker at a bank may choose to get approval for a new car loan or submit an overdue
loan request.

The ability to select work assignments at the user's discretion comprises the user-selected
assignment model.
Cases often consist of a series of tasks, assigned to users.
Completion of each assignment advances the case through its life cycle.
Assignments can go to a specific user, or to a general queue for a group. In the user-selected
assignment model, users choose from many pending assignments. Users must balance two goals:
performing the most important work first, and performing work appropriate for the user's skill set.
In the system-selected assignment model, you configure applications to choose user assignments
according to importance and required skills.
Get Next Work is the Pega term for system-selected assignment model. Get Next Work matches each
user with the appropriate assignments and prevents users from selecting preferred assignments
rather than high-priority assignments. For a financial-services firm, you can assign mortgage
application reviews to a general queue. Assignments for complex mortgages can be assigned to
underwriters with the appropriate expertise.

133
©2018 Pegasystems
System architects can configure applications to identify and present the assignment with the most
immediate need. The system can prioritize assignments from either the user's worklist or the
workbaskets a user can access. Allowing the application to prioritize the most important assignment is
the system-selected assignment model.
For example, a loan underwriting group pulls work from a common workbasket. The members of the
group specialize by loan type. You want to ensure that only group members, who are trained
underwriters, process mortgages. System architects use the system-selected model to determine how
the system chooses a user's next assignment. The system-selected model ensures that the right user
performs the right assignment.
For more information, refer to the help topic Get Next Work.
KNOWLEDGE CHECK

What concern does Get Next Work resolve?

Case workers selecting assignments that do not require immediate attention.

134
©2018 Pegasystems
How to manage assignment selection
Many business processes require storing tasks in a centralized workbasket. Users can then select a
task when ready for new work. The concern is that users only select desirable tasks, leaving the less
desirable tasks in the workbasket.
You can configure the application so that each time a user completes an assignment, the application
automatically selects the most appropriate assignment for the user to work on next.
Pega 7 provides a set of facilities called GetNextWork that helps match users to the next most
appropriate assignment. The GetNextWork functionality considers all eligible assignments to which a
user has access.
To control the order in which users complete work, answer the following questions:
l Will the user's worklist be checked for assignments first?
l Will the workbaskets a user is assigned to be checked for assignments first?
l If assignments come from one or more workbaskets, should the list of assignments be consolidated
into a single list before being filtered and sorted?

Checking the user's worklist for assignments first

The default behavior of the GetNextWork functionality in Pega 7 is to check the user's worklist for open
assignments.

When a user clicks the Next Assignment link, the system checks the user's work list. If assignments
are available in the user's work list, the assignments are filtered and sorted. The assignment ranked
with the highest priority is selected.
If no assignments are found in the user's worklist, the workbaskets associated with the user are
checked. If assignments are available in the workbaskets, the assignments are filtered and sorted. The
assignment ranked with the highest priority is selected.

135
©2018 Pegasystems
Getting assignments from workbaskets first
You can adjust the default settings to adapt how the system assigns work. For example, in some
organizations, users must work on the next available, highest priority task in a centralized work queue.

In the user's operator ID record, select the Get from workbaskets first option to configure the
application to check the workbaskets a user is associated with before checking the user's work list.

When the Get from workbaskets first option is selected, the workbaskets associated with the user
are checked first. If assignments are available in the workbaskets, the assignments are filtered and
sorted. The assignment ranked with the highest priority is selected.
If no assignments are found in the user's workbaskets, the user's work list is checked. If assignments
are available in the user's worklist, the assignments are filtered and sorted. The assignment ranked
with the highest priority is selected.
Note: By design, workbaskets are searched in the order they appear in the user's operator ID record.
The highest priority assignment in each workbasket is added to a final list of candidate assignments.
This final list of candidate assignments is then filtered and sorted again to find the assignment with
the highest priority.
KNOWLEDGE CHECK

136
©2018 Pegasystems
 What is the default search order of the GetNextWork functionality — worklist or workbasket?
Worklist

KNOWLEDGE CHECK

How do you change the default search order of the GetNextWork functionality?
In the Operator ID record, select the Get from workbaskets first option.

Consolidating assignments from multiple workbaskets into a single

list
If a user is assigned to multiple workbaskets, the task assigned could possibly come from the first
workbasket listed in the user's operator ID record regardless of the priority of tasks in other
workbaskets.

Use the Merge workbaskets option to organize all assignments in all of the workbaskets the user is
associated with into a single list before the list is filtered and sorted. In some applications, a user may
be associated to additional workbaskets other than the workbasket associated to the user's work group.
When the Merge workbaskets option is selected, use the Use all workbasket assignments in the
user’s work group option to limit the assignments available to the user to only those assignments
listed in the workbasket of the user's work group.
KNOWLEDGE CHECK

137
©2018 Pegasystems
 How do you configure the GetNextWork functionality to create a consolidated list of all
eligible assignments from all workbaskets to which a user is associated, before they are sorted and
ranked?

Select the Get from workbaskets first and Merge workbaskets options in the Operator ID record.

138
©2018 Pegasystems
 Delegating rules to business users
Introduction to delegating rules to business
users
When building a Pega 7 application, remember that it is designed to meet business needs. Business
needs reflect the operating environment of the business itself, and can change frequently and
unexpectedly.
Using Pega 7, you can delegate responsibility for updating selected parts of an application to business
users. Delegating business rules can help promote an agile response to changing business needs, and
empower those closest to the day-to-day business operations. Delegating business rules can also help
focus the workload for architects by transferring to the business the responsibility for maintaining low-
risk items.
After this lesson, you should be able to:
l Describe the use of rule delegation in an application
l Explain the benefits of rule delegation
l Delegate a rule for maintenance by business users

139
©2018 Pegasystems
Rule delegation
Every business application comprises a series of business processes that describe the steps a business
takes to achieve a specific business outcome.

Business processes are driven by policies that define what tasks must be completed, and when those
tasks must be completed. Business policies may even specify the order in which tasks must be
completed, or if certain tasks are necessary.

These business policies reflect the operating environment of the business itself, and can change
frequently — often unexpectedly. Changes to business polices can be caused by updates to internal
procedures, evolving industry guidelines, or changes in governmental regulations.

140
©2018 Pegasystems
When you model business policies in an application, you need to adopt a strategy to update these
models as business conditions change. Doing so enables the business to be more agile.
This approach also helps focus the workload for system architects. Rule delegation transfers the
responsibility for maintaining low-risk business policies to business users. This allows system
architects to concentrate on tasks suited to a longer, more rigorous development cycle. For example, a
business can delegate to the Human Resources (HR) department a service level agreement for
processing benefits enrollments. The HR department can adjust the details of the service level
agreement, allowing system architects to focus on other development tasks.

Keeping pace with change

Most changes to a business application occur within the scope of a development cycle.

A known set of business requirements are used to define the features and functionality for a specific
version of a business application. Each specific version of the business application is scheduled for
release on a certain date.

Business policies tend to change more frequently than any other part of a business application. If you
treat each business policy change as a change to the application, the result is either an endless series
of development projects, or the inability to keep up with the policy changes at the pace required by the
business.

141
©2018 Pegasystems
If you allow business users to update business policies, the business application can be adapted to
changes as they occur, rather than during the next update cycle. Designing the application so business
policies are owned and modified by business users can help promote an agile response to ever
changing business conditions. This design also empowers business users to make changes to business
policies as those changes occur.

Empowering business users with rule delegation

In Pega 7, rule delegation allows business users to make changes to business policies without
involvement from IT.
Using rule delegation, you put a set of policies under business control even while the application is in
production. Business users view the policies in a familiar environment, and can make updates to the
policies without knowing all the related, technical details.

Enabling business users to manage changes to business policies on their own helps the business be
more agile, and rely less on people outside of their control. This in turn allows system architects and
other technical members to spend more time on architectural decisions and implementation
strategies.
Adopting a rule delegation strategy significantly improves the business' ability to adapt to changing
business conditions, and allows business users and architects to focus on what they do well.
KNOWLEDGE CHECK

Delegating business rules can ________________ and ____________________.

promote an agile response to constantly changing business conditions
provide a level of empowerment to business users

142
©2018 Pegasystems
How to delegate rules to business users
Rule delegation enables business users to change simple application logic without involvement from
IT. Business user can make changes to the delegated rules without knowing all of the related, technical
details. For example, you can delegate correspondence or service level agreement rules to a business
line manager. The business line manager views the delegated rules and makes changes in the Case
Manager portal.
Several parties collaborate to perform the tasks necessary to delegate rules. The tasks listed in this
process are not considered sequential. They are listed in a logical order that makes them easier to
complete.
Note: Role assignments may vary, depending on the business requirements, project team size, and
project location.
l A business architect (BA) identifies the business users who manage the delegated rules.
l A senior system architect (SSA) or lead system architect (LSA) creates an access group for business
users responsible for managing the delegated rules.
l A system administrator organizes the business users who manage the delegated rules in the access
group.
Note: During development, an SSA may perform this task with test operators to test the
configuration.
l A BA identifies the rules to delegate.
l An SSA organizes the rules to delegate in a production ruleset. This ruleset must remain unlocked
in the production environment as changes cannot be made to rules in a locked ruleset.
Note: Depending on the customer, creating the rulesets used for delegating rules may fall to a
system administrator, an LSA, or others with detailed knowledge of the application structure.
l An SSA delegates the rules for availability in a user portal.

Create an access group for users who manage delegated

rules
Create an Access Group to organize the business users responsible for managing the delegated rules. A
separate access group for delegated rules simplifies the management of the delegated rules. The
access group includes the rights to view and modify the delegated rule while preventing other users
from making unauthorized changes.
Note: In some organizations, creating an access group may be the responsibility of a system
administrator or others who understand the application structure and security implementation.

Identify the rules to delegate

In Pega 7, there are no restrictions on which rules can be delegated. However, to be successful, your
rule delegation strategy must consider which rule types are best to delegate. In general, BAs work with
the business users to determine what components of the business logic — which rule types — they
want to maintain.

143
©2018 Pegasystems
Important: The business user's familiarity with managing rules is a key factor when deciding which
rules to delegate.
The best candidates for delegation are the rules most affected by frequently changing business
conditions such as correspondence, paragraphs, decision tables, service level agreements, or when
rules.
Start by delegating a small, focused set of decision rules and correspondence templates. As the
business users become more comfortable with delegation, you can expand the number and types of
delegated rules.

Organize the rules to delegate in an unlocked,

production ruleset
To update any rule on a production system, the rule must be contained in an unlocked ruleset. An
unlocked ruleset is a ruleset in which rules can be modified and saved.
An unlocked ruleset is a potential security risk, so it should be dedicated solely to delegated rules. This
allows a system administrator to prevent unauthorized access to critical process flows or case design
elements. Changes to these elements can have drastic effects on case processing.
Add the ruleset to the application rule as a production ruleset. A production ruleset is a ruleset
containing rules that can be modified after the application is deployed.
Using a production ruleset to organize and contain delegated rules insulates the rest of the application
from frequent changes. Because the original version of the rule still exists in a locked ruleset, a system
administrator can revert to the original copy if something happens to the delegated version of the rule.
Important: The ruleset containing the delegated rules must remain unlocked in production so
business users can make changes to the delegated rules. Changes cannot be made to a rule in a
locked ruleset.

Delegate the rule

Create a new rule, or open an existing one.
Important: Remember to add the rule you want to delegate to the ruleset created specifically for
delegated rules.
Delegate the rule to the access group used to organize the business users who will manage the
delegated rule. For example, a Human Resources (HR) department may send an email to a new
employee prior to the employee's first day of work. You can delegate the correspondence rule that
contains the email content to allow the HR department to update the email to reflect a different new
hire orientation procedure.

144
©2018 Pegasystems
Provide a meaningful title and detailed information about how the delegated rule affects the
application. For example, if delegating a decision table, include a detailed description such as: The logic
in this decision table determines whether a travel request requires additional manager approval. Changing the
logic in this decision table may affect all subsequent travel requests submitted in this application.
Note: To delegate a rule, your operator ID must be assigned to an available role that has the
pxCanDelegateRules privilege. By default, this privilege is extended to users assigned to the
Administrator or SysAdm4 access role. If you cannot delegate rules, contact your Pega 7 system
administrator to confirm that your operator ID has this privilege.
KNOWLEDGE CHECK

Why is organizing delegated rules in an unlocked ruleset necessary?

This is necessary so that business users can make changes to the rule. Rules in a locked ruleset
cannot be edited.

KNOWLEDGE CHECK

What two prerequisite tasks should you complete before attempting to delegate a rule?
1. Prepare an access group used only for granting access to delegated rules.
2. Organize the rules you want to delegate in an unlocked, production ruleset.

145
©2018 Pegasystems
Delegating a rule to business users
Delegating a rule enables business users to make changes to simple application logic without
involvement from architects or other technical team members.

Prerequisites to delegating a rule

Prior to delegating a rule, you must:
l Identify an access group responsible for managing delegated rules
Using a separate access group for delegated rules simplifies the management of the delegated
rules. The access group includes the rights to view and modify the delegated rule while preventing
other users from making unauthorized changes.
For help with access groups, see the Access Group Help topic.
l Copy the rule to a production ruleset
Organizing the rule in a production ruleset insulates the rest of the application from frequent
changes.
For help with making a copy of a rule, see the Copying a rule or data instance Help topic.
Important: The ruleset used to organize delegated rules must remain unlocked in the production
environment so business users can make changes to the delegated rules. Remember, changes
cannot be made to a rule in a locked ruleset.

Delegate the rule to users

1. Open the rule you want to delegate to users.
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 being delegated.
Note: See the Delegating a rule or data type help topic for detailed information on the available
options.

146
©2018 Pegasystems
4. In the Delegate to access group drop-down list, select the access group to which to delegate the
rule or data type.

5. In the Title field, enter a title for the delegated rule. Use a title that is meaningful in a business
context. For example, use New customer welcome email. Do not use Welcome email.

6. In the Detailed Description field, enter detailed information about the delegated rule. This text is
displayed to the business users to help them understand the rule, and the impact changes they
make to the rule may have on the application logic.
Provide information about how the delegated rule or data type affects the application. For example,
write: The logic in this delegated decision table determines whether a travel request requires additional

147
©2018 Pegasystems
 manager approval. Changing the logic in this decision table may affect all subsequent travel requests
submitted in this application.

7. Click Delegate.
8. Click Save to save your changes.

148
©2018 Pegasystems
 Configuring parallel processing
Introduction to configuring parallel
processing
In this lesson, you learn how to configure processing that allows two or more processes to proceed in
parallel as a case is processed. You also learn how to configure case locking.
After this lesson, you should be able to:
l Describe parallel processing
l Configure parallel processing for cases
l Describe case locking strategies
l Configure case locking

149
©2018 Pegasystems
Parallel processing in Pega applications
You can configure a stage to run multiple processes in parallel. This configuration allows users to
perform tasks independently in order to complete the work in a stage. For example, in the recruitment
stage, you can include a process for interviewing a candidate. In the same stage, you can include a
process for verifying a candidate's job history. Both processes can be started and completed
independently. When the interview and job verification are completed, the case moves to the next
stage.
For more complex parallel processing requirements, Pega provides the Split Join shape, the Split For
Each shape, and the spinoff option in the Subprocess shape.
The process to which you add the shape is called the main process. The shapes call one or more
subprocesses that proceed in parallel.

Split Join
You use the Split Join shape to call multiple independent processes that operate in parallel and then
later rejoin. For example, a mortgage application process may require that a user validates the home
buyer's credit history. At the same time, another user must perform a title search. Both of these
processes are unrelated and can be performed in subprocesses that proceed independently and in
parallel. When the subprocesses are complete, the main mortgage application process can continue.
This is similar to a parallel process in the case lifecycle — when all the processes in a stage are
completed, the case enters the next stage or is resolved.
However, the Split Join shape gives you the flexibility to use join conditions that determine when the
primary process can continue. The join condition may iterate over a when condition or a count to
determine when to resume the flow. For instance, a Split Join may include three separate approval
subprocesses. You can specify that only two of the three approvals must be completed before
resuming the main flow.

150
©2018 Pegasystems
Split For Each
A Split For Each shape allows you to run one subprocess multiple times by iterating through a set of
records stored in a page list or page group. When the items on the list have been processed, the main
flow continues. For example, you can use a Split For Each to iterate over a list of vendors and send a
quote request from each vendor on the list. Like the Split Join, you can use a join condition to control
when the primary process resumes. If you use an iterate join condition, you can start flows for
elements of the Page Group or Page List property one by one, and configure testing conditions to
determine whether to continue.

Spinoff
The spinoff option in the Subprocess shape allows you to run the subprocess in parallel with the main
flow. The main process does not wait for the subprocess to complete before proceeding. The spinoff
option is an advanced feature in the Subprocess shape and is accessed in the flow diagram.

KNOWLEDGE CHECK

Which type of Smart Shape would you use to start an interview processes based on a list of
employees who must interview a job candidate?

151
©2018 Pegasystems
A Split For Each allows you to iterate over a list of employees to start an interview process for each
employee.

152
©2018 Pegasystems
How to configure parallel processing
You configure Split For Each, Split Join, or Spinoff parallel processes in a flow diagram. To add a shape,
right-click and select a shape. For a Spinoff, select the Subprocess shape.

First, decide where in the flow you want to place the shape. After you place the shape, you open the
property panel and configure the properties. These properties vary depending upon the shape. For
example, in an interview flow, job candidates are scheduled for interviews. Each candidate is
interviewed by multiple employees. As each employee completes the interview, the employee submits
a candidate assessment in a subprocess. In this example, you place the Split For Each shape after an
assignment for scheduling an interview.

153
©2018 Pegasystems
Then, open the shape and configure the properties. For a Split For Each, you enter the page property
you want the process to iterate. The Split For Each functionality starts a new flow for each item on the
list. In this example, the property contains a list of interviewers. An InterviewCandidate flow is created
for each interviewer.

Note: When you use a Split For Each shape, make sure that the flow and the page list used in the
iteration are in the same class.
A Split Join shape allows you to call multiple subprocesses from the main process. In the following
example, the main process calls a background check and collects candidate details subprocesses,
which run in parallel with each other.

154
©2018 Pegasystems
To use the Spinoff parallel processing, you must open the Subprocess shape on the flow diagram and
select the Spinoff option. You can add subprocesses in the case life cycle by adding process steps.
However, to use the spinoff feature, you must configure the shape in the flow rule.

Embedded classes
Split Join shapes allow you to call a flow on an embedded page such as a data class. For example,
assume the Purchase Request case has an embedded page named .ShippingAddress and the data
class is ADV-Purchasing-Data-Address. Based on the specified address location, you can call a flow in
that data class. The flow is configured to check whether a Saturday delivery is possible for that
address. The subprocess returns a Yes or No result to the main process.

Join conditions
On Split For Each and Split Join shapes property forms, you specify a join condition. The join condition
setting controls when the main flow resumes.
l Select Any if you want the main flow to resume after any one of the subprocesses completes. At that
time, processing of the other subprocesses that have not completed is stopped. Open assignments

155
©2018 Pegasystems
 for these subprocesses are cancelled.
l Select All if you want the main flow to resume after all of the subprocesses complete.
l Select Some if you want to use a when rule or a count to determine when the main process can
resume.
The Split for Each shape also contains an Iterate join condition. This starts flows for items on the Page
Group or Page List property one by one, testing a when condition to determine whether to continue.
A Spinoff does not have a join condition because the subprocess never rejoins the main process.
KNOWLEDGE CHECK

In an equipment selection process, you want to start a Facilities Setup and IT Setup
processes to run in parallel using a smart shape. Which smart shape would you choose?
You would choose a Split Join because it lets you call multiple subprocess that run in parallel.

Configuring parallel processing

The following resources provide information to help you configure the parallel processes.
l For a description of how to configure a Split For Each shape to create a loop in a flow that iterates
over a group or list of pages, see the Help topic Adding iteration to a flow.
l For a description of how to configure a Split Join shape, see the Help topic Adding asynchronous
processing to a flow.

156
©2018 Pegasystems
Case locking
In most situations, when a user is working on a case, other users are locked out of the case until the
first user submits their case. This locking strategy prevents potential conflicts when a user attempts to
submit cases that have already been updated. Default locking in Pega locks the case when an
operator opens the case. If a second operator tries to open the same case, they get a message that the
case is locked by the first operator. The second operator is able to open the case in review mode only.
The lock is acquired when the case was opened by the first operator. The second operator cannot
access and update the case. By default, the system locks the case for 30 minutes or until the user
submits or closes the case, whichever comes first.

In certain situations, a business may want to allow more than one user to open a case at the same
time. For example, an insurance company may want to allow claims adjustors to make real-time
updates to a claim request. These updates could be adding a new item or adjusting the estimated cost.
The company may also want customer service representatives (CSRs) to have access to the request in
case the CSR needs to update the customer's personal information. The rationale is that the adjustor
and CSR will likely be updating different data and not risk overwriting the same data.
In those situations, optimistic locking enables both the operators to open the case. No lock is
obtained when the case is opened. The lock occurs when the user submits the case. When two
operators are working on the same case, the changes to the case are made by whoever submits the
case first. When the second operator submits the form, the operator receives a message with the first
operator’s name and the time of the change. The second operator clicks a refresh button in the
message to get the new changes made by the first operator. The second operator’s changes are not
applied until they submit their action after the refresh.

157
©2018 Pegasystems
Locking in the case type hierarchy
In a case type hierarchy, you configure case locking on the top-level parent. When child cases are
created, the parent's lock settings cascade down through all the child-case types. At run time, the lock
settings are applied to the child case you created. The standard setting is default locking. Assume the
parent case type, Onboarding, has a child case type, Benefits Enrollment. Both use default locking.
When a user opens a Benefits Enrollment case, it and its parent Onboarding case are locked. If default
locking hampers user throughput in your application, you can override the default locking setting at
the child-case level. This lets users concurrently make updates to parent cases and their child cases
without conflict.
The recommended approach for most situations is to lock the parent when the child case is being
worked on. Default locking helps preserve transaction integrity among cases. For example, the
Onboarding case may contain properties such as the total cost of benefits that are totaled from values
in the Benefits Enrollment case.
If you set the top-level parent case type to optimistic locking, all of the parent's child case also use
optimistic locking. You cannot override the setting at the child-case level.

Choosing a locking strategy

Choosing the right locking strategy depends on your organization's business requirements. If multiple
users will likely attempt updates to cases in one or more case types, you should use default locking.

158
©2018 Pegasystems
Optimistic locking may be called for where multiple users need only to open and review cases without
having to perform updates.
Also consider creating a child case type as an alternative to allowing multiple users perform tasks on
an open case. Using the previous insurance example, assume that you make Account Updates a child
case type of the Claim Request case type. This allows you to use default locking for both case types.
Users in both case types can make updates without causing conflicts.
KNOWLEDGE CHECK

Assume you want users to have the ability to work on top-level cases while their child cases
are open. How would you configure your locking settings?
For each child case, you override the default setting that locks the parent case.

159
©2018 Pegasystems
How to configure case locking
When working with a case type hierarchy, you set locking on the top parent case. The settings cascade
down to each child case when it is instantiated. If the child cases are instantiated as part of the parent
case, they have the same locking settings as the parent. In the Case Explorer, select the parent case
type to set locking. Then, in the Case Designer, on the Settings tab, select the Locking option. If you
select default locking, you can modify the default locking timeout of 30 minutes in the Release lock
after ________ mins field. Consider the business context when setting the timeout duration. For
instance, if a case will likely be opened frequently, you may want to shorten the timeout so that users
can more quickly access the case.

If you select default locking, you can update the lock timeout for any child cases. If you do not want to
lock the parent case if the child case is open, select the Do not lock the parent case when the child
case is opened check box.

For more information about the Locking option, see the Help topic Setting the locking strategy for a
case type.

160
©2018 Pegasystems
Locking standalone cases
Child cases may be instantiated independent of a parent case. For example, you may want to create a
shipping case as a standalone case that is not a child case of a purchase request parent case. If a child
case is instantiated as a standalone case, it does not inherit its lock settings. You can configure case
locking for this case type on the Advanced tab of the Case Type rule.

161
©2018 Pegasystems
 Improving the user experience with
screen flows
Introduction to improving the user
experience with screen flows
Screen flows are an efficient way to capture a lot of data at once from an end user. Screen flows divide
complex tasks into a series of steps. By splitting the task into a series of steps, you effectively simplify
the task.
After this lesson, you should be able to:
l Describe the purpose of a screen flow.
l Configure navigation and persistence options for a screen flow.

162
©2018 Pegasystems
Screen flows
Long, complex online forms can be difficult and frustrating for users of the application to navigate.

For example, online order forms require a lot of data. Users must enter their contact information, the
items they want to buy, and the payment method. They may also have to select a shipping method that
impacts the total cost of the order.
To help users complete complicated tasks, UX designers often design a guided, linear workflow using
simple UI screens. Each screen captures specific and related data such as order details or payment
information.

Users easily navigate these screens to enter data and complete tasks without frustration.
In Pega, a screen flow is used to create a linear series of UI screens. The screen flow allows users to
navigate multiple screens to enter data and complete tasks. Users can return to a prior screen to
change or review the input on each screen.

163
©2018 Pegasystems
The individual UI screens are part of a single form presented in a logical sequence. Users can complete
the UI screens in any order. At any point in the flow, users can review or change information on
previous screens.
Note: A screen flow represents a single assignment completed by a single user. Individual UI screens
in a screen flow cannot be routed to different users.
Screen flows present users with a road map to complete the task. The linear structure ensures users
focus on each step eliminating frustrations.
KNOWLEDGE CHECK

Screen flows can help users complete complicated tasks by __________________ .

presenting a linear workflow using simple UI screens

164
©2018 Pegasystems
How to configure a screen flow
A screen flow allows users to navigate multiple screens to enter data and complete tasks. Users can
return to a prior screen to change or review the input on each screen.
To configure a screen flow, determine the following:
l What type of navigation style will the screen flow use?
l What is the sequence of steps? Must users complete each screen in sequence, or can they complete
the screens in any order?
l What post-processing actions must execute? Must data be validated on each step, or only when the
screen flow is completed?
l What data, if any, needs to be persisted? Will data be saved on each screen, or only when the user
has completed all screens?

Configure the navigation style for the screen flow

Use a harness to define the navigation style for the screen flow. Pega 7 provides three harnesses you
can use to define the navigation style:
l TabbedScreenFlow7
l TreeNavigation7
l PerformScreenFlow
Note: The harness is configured on the Start shape when using the ScreenFlow process template.

TabbedScreenFlow7 harness
Use the TabbedScreenFlow7 harness to display the steps of the screen flow in a tabbed format.

This navigation option displays the current step of the screen flow highlighted in blue and shows all
the steps in a tabbed format. Users navigate using the Back and Next buttons, or by clicking on a tab.
Users can move forward or backward by clicking on a tab in the tab navigation.

165
©2018 Pegasystems
TreeNavigation7 harness
Use the TreeNavigation7 harness to display the steps of the screen flow in a tree structure format.

This navigation option displays the current step of the screen flow highlighted in blue and shows all
the steps in the navigation tree. Users navigate using the Back and Next buttons, or by clicking on the
menu item in the tree structure. Users can move forward or backward by clicking on a step in the tree
structure.

PerformScreenFlow harness
Use the PerformScreenFlow harness to display the steps of the screen flow as a trail of breadcrumbs.

Note: The PerformScreenFlow harness will only display the current and completed steps of the screen
flow.
Users navigate using the Back and Next buttons. Users can only move multiple steps backwards.

Configure the sequence of steps

Each assignment shape in a screen flow represents a step. Configure each assignment shape to
control the order in which the steps are executed.

166
©2018 Pegasystems
You can configure a screen flow so that:
l Steps are run in a strictly enforced sequence; that is, step 2 can only be executed after step 1, and
step 3 can only be executed after step 2.
l Steps are run in any order; users can move from step 1 to step 5, and then back to step 3.
To strictly enforce the sequence in which steps can be executed, select the Enable navigation link
and the Only allow navigating back to this step options on each assignment.
Note: One way to enforce a strict sequence is to use the PerformScreenFlow harness. This harness
displays a breadcrumb trail that does not include future steps. Users must use the Next button to
move to the next screen in the sequence.
To allow steps to be run in any order, select only the Enable navigation link option on each
assignment.
Caution: If you clear the Enable navigation link option on an assignment, the step will not display in
the navigation sequence, but will display to the end user when the step is encountered in the screen
flow.

This may confuse end users. As a best practice, use the Enable navigation link on all steps.

Configure post-processing actions

When using the screen flow template, post-processing actions listed on the flow actions are not
automatically executed. You can force post-processing actions to execute by selecting the Perform
post-processing when navigating away from step option on each assignment. When the process
moves from the step, any validation rules and post processing rules listed in the flow action are
executed.
Examples of leaving a shape at run time include clicking another entry point in the navigation
sequence or automatically moving to the next step in the sequence when the current step is
completed.

Configure the persistence options

When using the screen flow template, each step in the screen flow is committed to the database as it is
executed.
Use the Save on last step option on the Start shape to prevent commits to the database as each step
is executed. When the option is selected, the data collected on each of the assignments is not saved
until the last step.

167
©2018 Pegasystems
Use the Allow errors option to allow users to progress the screen flow to a different step even if the
current step fails validation.
Note: The Allow errors option is often used with the Save on last step option.
Tip: As a best practice, select the Save on last step option to reduce the number of case and history
commit operations.

168
©2018 Pegasystems
Configuring a screen flow
Configure a screen flow to allow users to navigate multiple screens to enter data and complete tasks.
To configure a screen flow, create a flow record using the standard template for screen flows. Next,
configure the screen flow navigation style and the sequence of steps. Then, configure post-processing
options. Finally, configure persistence.

Create a new flow record using the screen flow template

A screen flow is a special type of flow. To configure a screen flow, first create a flow record and specify
the screen flow template.
Note: By design, flow records are created using the standard flow template, and cannot be converted
to a different template.
1. Create a new flow record.
2. Click View additional configuration options.
3. Select the Standard template for screen flows option.
4. Click Create and open to create and open a screen flow that contains a Start shape, a single
Assignment shape, and an End shape.

Configure the screen flow navigation style

Use a harness to define the navigation options for the screen flow. The harness is configured on the
Start shape.
Note: When using a screen flow, the harness rule is configured on the Start shape. Because of this, a
screen flow can only use one type of navigation style.
1. Double-click the Start shape to open the properties panel.
2. In the Harness field, press the down arrow key and select a harness that defines the presentation
of the screen flow.
3. Click Submit to close the properties panel.

Configure the sequence of steps

By design, all steps in a screen flow are presented in the navigation sequence. To make changes to
how steps are presented in the navigation sequence:
1. Double-click an Assignment shape to open the properties panel.
2. Clear the check box for the Enable navigation link option to prevent users from advancing to the
step.

169
©2018 Pegasystems
 Caution: If you clear the Enable navigation link option on an assignment, the step will not display
in the navigation sequence. The step displays to the end user when the step is encountered in the
screen flow sequence. This may confuse end users. As a best practice, use the Enable navigation
link on all steps in a screen flow to ensure that the step is always displayed in the navigation
sequence.
3. Select the Only allow navigating back to this step option to prevent users from skipping ahead to
this step before the preceding steps are completed.
Tip: As a best practice, select the Only allow navigating back to this step option for cases that
are accessed on mobile devices. When using a computer-based browser, clearing this check box
provides the most flexibility because users can process steps in any order.
4. Click Submit to close the properties panel.

Configure post-processing actions

In a screen flow, post-processing actions listed on the flow action are not automatically executed.
Follow these steps to force post-processing actions to execute:
1. Double-click an Assignment shape to open the properties panel.
2. Select the Perform post-processing when navigating away from step option to run validation
and post-processing actions each time a user leaves the shape.
3. Click Submit to close the properties panel.

Configure persistence options

In a screen flow, Pega commits each step to the database as the step executes. To prevent commits to
the database when each step is executed:
1. Double-click the Start shape to open the properties panel.
2. Select the Save on Last Step option to prevent commits to the database when each step is
executed.
3. Click Submit to close the properties panel.
Remember to save your changes to the screen flow record.

170
©2018 Pegasystems
 Adding attachments
Introduction to adding attachments
Many cases need associated assets such as files, screen captures, and scanned documents to
substantiate the case. You can also use Pega's internal security precautions to provide users access to
search, view, add, and edit the attachments.
After this lesson, you should be able to:
l Describe the purpose of attachments
l Configure the ability to add attachments manually to a case
l Configure the ability to add attachments automatically to a case
l Control user access to attachments

171
©2018 Pegasystems
Attachments
During case processing, end users may need to attach documentation containing additional
information. For example, an insurance claim for a car accident might need the police report to identify
who is at fault. A case attachment can be a file, screen shot capture, URL, or text note.
This video illustrates attachment options.
Many cases require associated documentation and assets such as files, screenshots, and scanned
documents.
You use out-of-the-box tools to attach files to a case for further reference. You can use security
precautions to ensure that only people who are allowed access to a specific case file can edit the
attachments.
For example, a legal secretary can attach a scanned legal document, making it into an editable PDF.
When another member of the legal team needs to review the case documents, the team member can
access the secured document.
When the team needs to look for a specific type of attachment within the case, the search is based on
filter criteria, such as all file attachments.
Pega 7 supports configuring a case type to add attachments manually and automatically, as required
by the specific application.
Pega 7 supports security and access restrictions for certain attachment options. For example, any
member of the claims processing group may add attachments, while only claims managers have the
right to delete attachments. You use the Attachment Category rule type to enable security and
restrict access for certain attachment operations and organize and classify attachments. You can
differentiate between a police report and a repair estimate and assign each a different access
restriction.

Attachment file conversion and editing

When a user designates a file as an attachment, the system uploads a copy of the file and links it to the
history of the work item. The system saves attachments for correspondence in HTML format (.htm file
type) even if a user edited the correspondence with Microsoft Word. If the correspondence includes
embedded images or other embedded objects, the attachment is saved as a .zip archive containing the
objects and the .htm file. The system converts the .zip file internally into characters using Base64
encoding.
File attachments are normally a permanent read-only part of the history of a work item. However, in
some applications, you can edit and update the attached file (using Windows workstation software),
creating a higher-numbered version of the file attachment. The application retains all versions, in
sequence. You can edit the description of a new version to add a number or other distinguishing
information.
For example, a photograph stored as a .jpg file might be difficult to interpret or might contain
extraneous material. When rules have the appropriate configuration, you can open and manipulate the
.jpg file (using Windows imaging software) to crop, filter, or annotate the image. Pega 7 Platform retains
the original unaltered file as the first edition and the updated file as the second edition.
Similarly, you can edit a project plan file with Microsoft Project, or revise a Microsoft Word document.

172
©2018 Pegasystems
The standard flow action Work-.EditAttachment supports opening and editing file attachments.

Attachment classes
An attachment is an object of a class that inherits from the Data-WorkAttach class. Pega provides
several standard classes to describe attachments.
Data-WorkAttach-File — Holds files of any type and format, including PDF files generated by an
application
Data-WorkAttach-Note — Contains text that is pasted into, or typed directly into, a work item
Data-WorkAttach-URL — Records an Internet Uniform Resource Locator (URL) or Uniform Resource
Identifier (URI)
Data-WorkAttach-ScreenShot — Holds screen shot attachments that usually record facts about the
work item that were obtained from another system
Data-WorkAttach-ScanDocument — Contains a TIFF image file created by a scanner
Data-WorkAttach-ECM — File attachments saved in an external enterprise content management
(ECM) system, accessed through a Connect CMIS rule
Attachments are stored in a different database table than cases. By default, attachments are stored as
rows in the pc_data_workattach table.
KNOWLEDGE CHECK

Pega supports attaching documentation to cases. Name the documentation feature that
must be specifically configured.
Security and access restrictions for certain attachment options

173
©2018 Pegasystems
How to configure a case to accept
attachments
You use standard perform and review harnesses to enable users to add attachments to a case. The
add attachment function is built into the standard user interface (UI). End users access the Case
Attachments section to add attachments.
The ability to add attachments may be unavailable with custom perform or review harnesses. System
architects may configure a local add attachment action or select one of the available standard flow
actions. You can also configure local actions for UI events. End users select local actions from the Other
actions menu.

Enterprise Content Management attachments

Pega provides the ability to configure external attachment storage. Pega uses a Content Management
Interoperability Services (CMIS) protocol to connect with an external enterprise content management
system (ECM). Compatible CMIS protocols include Microsoft SharePoint and IBM FileNet.

On the application rule Integration tab, select the Enable for attachments check box to enable
external storage.
Next, in the Connector Name field, specify the Connect CMIS rule used to connect to the external CMS
system. If necessary, click the Magnifying glass icon to create a new Connect CMIS rule.
In the CMIS Folder field, use the Browse button to select the content management system storage
directory.
Anyone who has access to a particular case can view the list and content of the attachments. Case
access is subject to the security configuration for the category.
The Advanced attachments window groups attachments by type. You use the attachments section in
the harnesses for quick viewing.

Attach Content smart shape

You use the Attach Content smart shape to add a specific file, note, or URL automatically to a case (for
example, a standard Terms and Conditions form for user review). You can configure the Attach Content

174
©2018 Pegasystems
shape after you add it to a flow. By customizing the shape, you can control the kind of information that
is attached to the case at run time.
Double clicking in the Attach Content smart shape displays the attachment type selection list. You can
select the format of the expected attachment. You also enter data specific to the attachment file
format, including a description, the external file storage location (if relevant), and any relevant rule
name. The Attachment Category field is optional.
KNOWLEDGE CHECK

The ability to add attachments to a case is available out-of-the-box. Which attachment

function must be configured by system architects?
External attachment storage

175
©2018 Pegasystems
How to configure attachment access
Pega 7 enables case attachment access and edit control through attachment categories.
An attachment category rule represents a business classification indicating the attachment content
or significance. The attachment category controls operations on attachments including create, edit,
review, and delete. Attachment categories are part of the Security category and are instances of the
Rule-Obj-AttachmentCategory rule type. Users can select an attachment category when adding
attachments to work items.
This screen capture shows the standard File Attachment Category rule.

You can specialize the file attachment category rule by copying it to a different ruleset and Applies To
class.
You can reuse the standard categories or create new attachment category rule instances, such as
invoice and packing slip.
You use the Security tab to control access to the attachments through privileges and when rules. In the
ACCESS CONTROL LIST BY PRIVILEGE section, in the PRIVILEGE NAME field, you select a privilege rule.
The system uses the Applies to class of the attachment category to validate the privilege name.
Select any of the following check boxes that apply:
l CREATE — Add category attachments
l EDIT — Edit category attachments
l VIEW — View category attachments
l DELETE OWN — Delete category attachments that they added earlier
l DELETE ANY — Delete any category attachments

176
©2018 Pegasystems
You can use the Add a row icon to add multiple privileges. The order of rows in this section is not
significant. In categories with multiple rows, users must hold at least one privilege to gain access.
You can define a list of when rules to control access to the attachments. All when rules must evaluate
to true for a qualified user to be granted access.
In the ACCESS CONTROL LIST BY WHEN RULE section, in the RULE field, you select a when rule. The
system uses the Applies to class of the attachment category rule to find the when rule. Next, select any
of the operation check boxes that apply.
The Enable Attachment Level Security option allows the operator who attaches a work attachment of
this category to identify one or more work groups that have access to the attachment.
When enabled, the attachment-level restriction operates in addition to and independently of any
restrictions defined on the tab for the category.
The Availability tab provides a list of the attachment types.

You select the check boxes for the attachment types that are valid for the category and the work type
identified by the Applies to class of this attachment category rule. In this example, only File
attachments are valid for the category.
If no types are selected, a default category rule in Work- class is used for its respective type. The
default category has no security restrictions.
KNOWLEDGE CHECK

What is the purpose of attachment categories?

The attachment category controls operations on attachments including create, edit, review, and
delete. Attachment categories are part of the Security category and are instances of the Rule-Obj-
AttachmentCategory rule type. Users can select an attachment category when adding attachments to
work items.

177
©2018 Pegasystems
Configuring flow action pre- and post-
processing
Introduction to configuring flow action pre-
and post-processing
In Pega, you can add pre- and post-processing actions to a flow action to manipulate data. These
actions enable you to add related tasks to the flow action. For example, you can concatenate a person's
first name and last name to create their full name.
After this lesson, you should be able to:
l Explain how pre- and post-processing configurations affect flow actions
l Configure pre- and post-processing actions for a flow action

178
©2018 Pegasystems
Pre- and post-processing in flow actions
Sometimes you need to perform a set-up or wrap-up action in conjunction with a flow action. For
example, you may need to initialize items in a list or copy data from one property to another. To satisfy
these needs, you can add pre-processing and post-processing actions to a flow action.
Consider an example of a trip case type. TGB hosts an annual meeting for employees and vendors.
TGB's employees use the trip case type to finalize travel arrangements for all business trips.
Approximately 60% of the trip cases processed are for the annual company meeting. TGB's application
requirements include creating a default event for the annual company meeting. Default values
populate the event form at rendering. If the user removes the default event, the event values do not
populate again. The case type must also be suitable for all company travel requests.
You can use a data transform to populate the annual company meeting on the event form as a pre-
processing action. The first time a user opens the form, the data transform populates the event on the
form. Creation of the default event occurs when the user selects the flow action, or automatically if the
flow action is the default action for the assignment.
Note: When you configure a flow action with a pre-processing action, Pega performs the action
whenever a user selects the flow action and each time the user is presented with the assignment. In
the preceding use case for a trip case type, if the user completes the assignment and later returns to
the assignment — for example, to update the details of their trip — the event re-populates on the
form. For this reason, add logic to a pre-processing data transform or activity to test whether to
perform the action.

Another common use case for post-processing is when a customer's billing address is also the
shipping address. A data transform copies the property values from the billing address page to the
shipping address page when a box is selected. You add the data transform to the flow action as a post-
processing action. When the user submits the form, the application copies the contents of the billing
address page to the shipping address page.
When you configure a flow action with a post-processing action, Pega performs the action each time
you perform the action. In the previous example of a billing address, each time the user submits the
billing address form, Pega performs the post-processing action to copy the billing address to the
shipping address.

179
©2018 Pegasystems
Tip: Verify that adding an action to the flow action is the best way to perform the action. For example,
when configuring concatenation of a user's first and last names, consider using a declare expression.
The concatenation is performed only when needed with a declare expression. With a pre- or post-
processing on the flow action, the concatenation is performed every time.
KNOWLEDGE CHECK

If a flow action includes a pre-processing data transform or activity, when does Pega
perform the action?
Pega performs the pre-processing action each time the flow action is presented to the user.

180
©2018 Pegasystems
How to configure pre- and post-processing
for flow actions
When considering whether to add a data transform or activity to a flow action as either a pre- or post-
processing action, analyze the requirement and the case type.
Consider the impact of a pre- or post-processing action when configuring the data transform or
activity. For example, if you add a pre-processing action to initialize a value or a list, you may not want
to repeat it if you reload the flow action. You should add logic to test if the value or list is already
initialized.
For a pre-processing action, another consideration is flow action likelihood. Pega automatically loads
the flow action with the highest likelihood, so a pre-processing action on the flow action automatically
executes when the user reaches an assignment.
The primary concern is the use case. Reusing application components and the Situational Layer Cake
are key Pega benefits. You can add actions and data transforms to a flow action both before and after
processing. Whenever an application uses the flow action, Pega performs the pre-or post-processing
action. If a pre- or post-processing action is only applicable to one case type, then specialize the flow
action for the case type before adding the pre-or post-processing action.
You analyze the requirement and the case type. Identify the affected flow action. Determine the
appropriate location for the new data transform or activity, before or after the flow action executes.
When the data transform or activity is ready, locate the Action tab of the Flow Action form for the
appropriate process. Select the data transform or activity to apply and enter it in the Pre-processing
or Post-processing section as appropriate. Selecting and entering the data transform or activity
completes the form.

181
©2018 Pegasystems
For more detailed information on completing the Flow Action form, read the Help topic, Flow Action
Form, Completing the Action Tab.
To see an example of creating data transforms and then using the data transforms as pre- and post-
flow action processing, read Using Data Transforms in Flow Actions.
KNOWLEDGE CHECK

Why is analyzing the requirement and the case type important?

You need to identify the impacted flow action and determine whether the new data transform or
activity should be placed before or after the flow action. You also create or update the desired data
transform or activity.

182
©2018 Pegasystems
 Circumstancing rules on multiple
variables
Introduction to circumstancing rules on
multiple variables
In this lesson, you learn how to create a circumstanced rule that is based on multiple variables. You
also learn how circumstancing impacts rule resolution.
After this lesson, you should be able to:
l Describe how circumstancing affects rule resolution
l Explain how Pega supports circumstancing rules on multiple variables
l Override circumstances with a base rule
l Circumstance a rule on multiple variables

183
©2018 Pegasystems
How to circumstance a record with multiple
variables
You use multivariate circumstancing when you want to use multiple properties to circumstance a
record. The first thing you do to configure multivariate circumstancing is create a Circumstance
Template. After creating a template, you create one or more Circumstance Definitions. Then, using the
Circumstance Template, you circumstance the rule.

Creating a Circumstance Template

A Circumstance Template defines the properties used to determine if the circumstance is valid. For
example, an internet provider wants to circumstance a correspondence based on the state the
customer lives in and the reward level. You would create a Circumstance Template that defines the
state and reward level properties.

To create a new Circumstance Template, reference this Help topic: New Circumstance Template.

Creating a Circumstance Definition

After you define a Circumstance Template, you create one or more Circumstance Definitions that use
the template. A Circumstance Definition defines the values for the Circumstance Template. The
values determine if the Circumstance executes. In the internet provider example, you create
Circumstance Definitions for each combination of state and reward level as needed. You do not have to
account for all possible combinations. If a combination does not have a Circumstance Definition
defined, the rule resolution algorithm uses the base rule.

184
©2018 Pegasystems
To create a new Circumstance Definition, reference this Help topic: New Circumstance Definition.

Circumstance a record using the Circumstance Template

After you create a Circumstance Template and one or more Circumstance Definitions, you
circumstance the appropriate record. In the Internet provider example, you would circumstance the
correspondence record and reference the Circumstance Template that uses state and RewardLevel.
To add a circumstance to a record, reference this Help topic: Specializing a record.
KNOWLEDGE CHECK

What are the three activities you must complete to configure multivariate circumstancing?
1. Create a Circumstance Template
2. Create one or more Circumstance Definitions
3. Circumstance the record and use the Circumstance Template

Circumstancing on multiple properties

You may have a business case that requires you to circumstance on multiple properties. For example,
mortgage rates are typically impacted by the type of property and the type of customer. You can do the
following things to implement this:
l Circumstance a base rule that is already circumstanced with a different property. Multiple property
circumstancing in this way is possible only when the circumstanced rules are in different rulesets
or Applies To classes. For example, a MortgageRate rule that is circumstanced by the PropertyType
property can be circumstanced again by the CustomerSegment property.

l Circumstance a rule by a different property in the same ruleset by withdrawing the existing
circumstanced versions. The circumstanced version must be in the higher ruleset version. For

185
©2018 Pegasystems
example, a MortagageRate rule that was circumstanced by the PropertyType property can be
circumstanced again by a different property, CustomerSegment, in a higher ruleset version after the
rule MortgageRate(PropertyType) is withdrawn.

Note: If you withdraw a circumstanced rule in a ruleset version, you cannot specialize the base rule
again in that ruleset version.

186
©2018 Pegasystems
How circumstancing affects rule resolution
Rule resolution of circumstanced rules
When several circumstanced versions of the base rule are available, the rule resolution algorithm
selects a rule based on the availability of rules in the higher ruleset versions as shown in the following
table.

Circumstanced rule Circumstanced rule Base rule in Result

in higher ruleset in lower ruleset higher ruleset
True True True Circumstanced rule in higher
ruleset version is resolved
True False True Circumstanced rule in higher
ruleset version is resolved
False True True Base rule in higher ruleset
version is resolved
False False True Base rule in higher ruleset
version is resolved

Watch the following video to understand how rule resolution and circumstancing work.
KNOWLEDGE CHECK

You have a circumstanced rule in a lower ruleset and a base rule in a higher ruleset. Which
rule would run?
The base rule in the higher ruleset

187
©2018 Pegasystems
How to override circumstanced rule
When the rule resolution algorithm determines the ranking of a rule, the version of the rule is less
important than the circumstance. Understanding how the rule resolution algorithm processes
circumstancing is important when updating one of the variations of the rule, or the base rule itself.
Consider the following circumstance:
During tax season, complete the request in two days instead of three.
What if there is a requirement that requires the base rule to change from three days to four days?
Updating the base rule is easy — you save the rule into a new version of the rule and update it. You do
not need to save the circumstanced versions of the rules because the rule resolution algorithm ranks
version as less important than the circumstance. So it is possible to have a circumstanced rule in
version 01-01-01 and the base rule in 01-01-15. At run time, if the rule matches the circumstance, then
the rule from version 01-01-01 executes. Otherwise, the rule from version 01-01-15 executes.
You have two choices to remove a circumstance: override the base rule, or override the rule by
withdrawing it.

Overriding a circumstanced rule with the base rule

One way to override a circumstanced rule is by defining a new base rule. You use this method when
you want to override all circumstances for a given rule. When a rule is marked as a base rule, all
previous circumstances are ignored during rule resolution.
Any version of any rule that can be circumstanced can also be designated as a base rule. When setting
the rule’s availability, check the Base rule option to designate a rule as a base rule.

Selecting the Base rule option indicates that this version of the rule is now considered this rule’s base
and any previous circumstances no longer apply. Consider an example where you vary the welcome
email based on the department a new employee is in.
The following table lists of all variations of a correspondence rule.

Version Circumstance
1 01-01-01 None

188
©2018 Pegasystems
 2 01-01-01 .Dept = Accounting
3 01-01-01 .Dept = Engineering
4 01-01-15 None
5 01-01-20 .Dept = Engineering
6 01-01-25 None, Base rule Checked
7 01-01-30 .Dept = Accounting
8 01-01-35 None

Based on the information in the list, if you execute this rule when .Dept= Accounting, Pega uses the
version of the rule on line 7 (ver. 01-01-30). If you execute this rule when .Dept = Engineering, Pega Uses
the version of the rule on line 8 (ver. 01-01-35).
This is because the rule on line 6 (ver. 01-01-25) has the base rule checked. All the rules previous to
this version (rules 1 through 5) are no longer applicable to the ranking. When the system looks at only
those rules available for ranking, the circumstance for Engineering is not applicable. As a result, the
highest version of the rule with no circumstances defined is chosen.

Overriding a circumstanced rule by withdrawing a rule

You can also override a circumstanced rule by adding a withdrawn rule with the same circumstance.
You use this method of overriding when the circumstance is no longer needed.
You must create this withdrawn rule in a higher ruleset version than the original rule to be deleted or
blocked so it is chosen first in rule resolution. You must also define the new rule with the same
characteristics as the rule to be withdrawn:
l Same defined-on (Applies To) class
l Same qualifiers (Circumstance Property, Property Value, Date Property, Date Property Value, Start
Date, or End Date)
l Same ruleset name
l Same major version
Using the previous example, if the requirement is to remove the circumstance because the engineering
department is no longer an exception, you would withdraw that circumstance and not impact the base
rule or the accounting circumstance.

Version Circumstance
1 01-01-01 None
2 01-01-01 .Dept = Accounting
3 01-01-01 .Dept = Engineering
4 01-01-15 None
5 01-01-20 .Dept = Engineering

189
©2018 Pegasystems
 6 01-01-30 .Dept = Engineering, Withdrawn
7 01-01-30 .Dept = Accounting
8 01-01-35 None

Create a new rule as shown in line 6 to remove the circumstance where .Dept=Engineering.
KNOWLEDGE CHECK

What are the two ways to override a circumstance rule?

Override the base rule, or withdraw a rule in a higher ruleset.

190
©2018 Pegasystems
UI DESIGN

191
©2018 Pegasystems
 Customizing a user portal
Introduction to customizing a user portal
User portals provide application users with the tools and options needed to work with a Pega
application. Each portal is tailored to a specific user role. In this lesson, you learn how to customize a
portal for application users.
After this lesson, you should be able to:
l Explain the role of user portals in applications
l Explain the role of a harness in a Pega UI
l Explain how user portals are organized
l Customize a user portal

192
©2018 Pegasystems
User portals
Applications often support multiple types of users, such as case workers and managers. Each type of
user interacts with the application in a unique manner. For example, case workers create and process
cases, while managers track the progress of cases. Each type of user needs access to tools and features
that support their role in case processing.
A user portal is the application user’s view into the application. Pega provides several user portals.
Each portal is customized to the needs of a specific type of user. For example, case workers can use
their portal to create new work, complete existing work, and run reports. Managers can use their portal
to monitor cases in progress and run reports that show case worker and case metrics.

Pega provides default portals for case workers and managers. While these portals can be used in an
application as is, some situations require that you customize the layout of the portal or the tools
presented to the user.
KNOWLEDGE CHECK

What is the purpose of a user portal?

The purpose of a user portal is to provide users with a view into their application. Each portal is
customized to the needs of a particular group of users.

193
©2018 Pegasystems
Harnesses
Pega encourages architects to follow the principles of modular application design, including user
interface (UI) design. To promote modular design, Pega provides different types of UI records for
content, structure, and formatting. Harness records describe the structure of the UI.

Harness records
A harness organizes the structure of a portion of the user display. In Pega, you use a harness to
organize either a work form or a portal.
Pega applications commonly use four standard harnesses to organize the content of user forms.

Harness name Usage

New Supports the creation of new cases.
Perform Enables users to select a flow action to perform to complete an assignment.
Review Presents an assignment in read-only mode, preventing data entry.
Confiirm Presents a read-only confirmation of completion of an assignment if the next
assignment is not performed by the user.

Pega also provides harnesses specialized for organizing user forms in screen flows. For a full list of the
standard harnesses available in Pega, see the Help topic Standard harnesses.
Harnesses that allow users to select a flow action and complete an assignment contain an action
area. When users select a flow action to perform, such as an approval form, Pega displays the content
for the selected flow action in the action area.
KNOWLEDGE CHECK

What is the purpose of an action area in a harness?

An action area displays the content of a user form when users select a flow action. The action area
describes the work users perform to complete an assignment.

Harnesses that organize a user portal contain a screen layout. A screen layout organizes the elements
of the browser window into a main content pane and smaller surrounding panes. For example, the
Header Left screen layout divides the portal into three areas: a header, a smaller left pane for
navigation, and a larger content pane for displaying cases and reports.

194
©2018 Pegasystems
Each pane of the screen layout references a section that contains the content displayed in the pane. To
modify the content in these sections, you use Live UI to identify and open the section to configure.
KNOWLEDGE CHECK

What is the purpose of a screen layout in a harness?

A screen layout defines the structure or a portal. The screen layout defines the panes of the
portal. The content of each pane is determined by referencing a section.

195
©2018 Pegasystems
How to customize a user portal
You can customize the default end-user portals provided in Pega to meet many project requirements.
If the requirements are complex enough, you can also create a custom application portal.
In Pega, a portal is represented with a portal rule. A portal rule identifies the type of user expected to
use the portal, the harness used to organize the portal contents, and the skin that defines the
branding applied to the portal.
To configure a Pega portal, you:
l Identify the intended user role and portal type
l Organize the layout of the portal
l Customize the branding of the portal
l Customize the content and tools available to users
l Configure an access group to reference the portal if necessary
Portal records are listed in the User Interface category in both the Records Explorer and the +Create
menu.
Note: Portal records are classless and do not appear in the App Explorer.

Identify the intended user role and portal type

In Pega, you configure a portal for use by either users or developers. User portals are intended for
users who do not routinely need to update rules. Developer portals are intended for system architects
and business architects, who routinely update rules. User portals require less memory on the user's
workstation than developer portals. Unless the intended user configures rules on a daily basis,
configure a new portal as a user portal.
Note: Users can configure delegated rules in a user portal.
Pega supports two portal types: composite and custom. Composite portals are defined by harnesses
and sections. Composite portals are cross-browser compatible and support Microsoft Internet Explorer,
Mozilla Firefox, Apple Safari, and Google Chrome browsers. Custom portals are defined by an activity.
As a best practice, configure a new portal as a composite portal.
You select the user role and portal type on the Details tab of the portal record.

Organize the layout of the portal

The organization of the portal affects how the contents of the portal are presented to the user. The
default user portals are organized with a header, a left navigation pane, and a content pane. To change
the layout of the portal, you change the screen layout used in the harness. To modify the content in
these sections, you use Live UI to identify and open the section to configure.
To create a new layout for a portal, create a new harness in the Data-Portal class, and add a section
layout to the portal. Then reference the harness on the Details tab of the portal record.

196
©2018 Pegasystems
Change the branding of the portal
You can customize the appearance of a portal by applying a skin. Skins contain instructions for
formatting elements of the user interface, such as text size, font style, and background color. To
customize the appearance of a portal, you choose between applying the application skin to the portal
and configuring a skin for the portal.
When you select the application skin, Pega applies the skin for the active application to the portal. If
the user switches applications, Pega applies the skin for the new application to the portal. If you create
a new portal, Pega configures the portal to default to the application skin.
To apply a skin to the portal, rather than reusing the application skin, select the Other skin option on
the Details tab of the portal record, then enter or select the skin to apply. For example, a portal is used
across an entire organization. Within the organization, each division customizes its branding, including
fonts and color schemes. In this situation, consider applying a skin to the portal to prevent changes to
the portal when users switch between applications.

Customize the content and tools available to users

You can add or remove content displayed in a portal by updating the sections referenced in the screen
layout. To modify portal content, use Live UI to identify and open the section to update. To override
records provided in the UI-Kit-7 ruleset for standard portals, copy the record into an application
ruleset.

Customize portal menus

You can add a menu to a portal by using a navigation record. A navigation record defines the entries
in a menu and the action performed when a user selects the menu item. Navigation records are used
to organize the menus displayed in standard portals such as the Case Manager and Case Worker
portals.
A navigation record contains a list of menu items. For each menu item, you associate a click event and
resulting action, such as logging off or displaying a harness.
For information on configuring entries in a menu using a navigation record, see the Help topic
Navigation form — Completing the Editor tab.
For information on configuring an action for an entry in a navigation record, see the Help topic
Navigation rule — Completing the Node Details Action tab.
For an example of configuring a navigation record, see the Community article How to create context
menus for grid layouts using navigation rules.
Navigation records are organized in the User Interface category in the Records Explorer and the
+Create menu.
KNOWLEDGE CHECK

What is the purpose of a navigation record?

A navigation record is used to configure the entries on a menu. It lists a menu entry and identifies
the action performed when a user selects the entry.

197
©2018 Pegasystems
Replace the Pega logo
You can update the icon displayed in the upper left corner of the portal. Standard Pega 7 portals
display the Pega 7 icon. You can update the portal configuration to display a different icon, such as a
company logo. To add an image or other non-text file to a Pega application, you create a binary file
record. A binary file record acts as a wrapper for the file, providing the security, inheritance,
versioning, and deployment benefits of rule resolution.
To update the icon displayed in a portal, create a binary file record for the icon, then use Live UI to
identify and update the section containing the icon. For instructions on configuring a binary file record,
see the Help topic Binary File rules — Completing the Main tab.
Binary files are organized in the Technical category in the Records Explorer and the +Create menu.
KNOWLEDGE CHECK

What benefits does a binary file record provide for storing non-text files?
A binary file record is a container for a non-text file. It provides the security, inheritance, versioning,
and deployment benefits granted through the process of rule resolution.

Customize the dashboard content

You can customize the content displayed on the dashboard of the Case Manager portal. For example, a
manager often wants to view the status of cases processed by their unit or work group. You can
configure the Case Manager portal to display one or more dashboard widgets that provide insight
into the status and progress of open cases. Dashboard widgets are organized into two or more slots
using a dashboard template.
To customize the dashboard, determine the template to use to organize the dashboard, then add
widgets to each slot. For example, to display a report on the dashboard, add the Report widget to a slot,
then select the report to display. For a list of widgets available in Pega, see the Help topic Dashboard
widgets. For instructions on adding a widget to the dashboard, see the Help topic Adding a widget.
Tip: You can also create dashboard widgets. For instructions on creating widgets, see the Community
article Quick start: Creating a dashboard widget.
After you finish adding or removing widgets from the dashboard, you can publish the dashboard as a
default dashboard for use by managers.
Note: Users of the Case Manager portal can personalize their dashboard with any of the standard
widgets provided in Pega, or any custom widgets you create. Once a manager customizes and
publishes their dashboard, they no longer view any changes you make to the default dashboard.

Configure an access group to reference the portal

To provide users with access to a user portal, add the portal to one or more access groups. To add a
portal to an access group, list the portal in the Available portals section of the Advanced tab of the
access group record. For each access group, you select one portal for Pega to use as the default portal.
Pega presents the default portal to a user when the user first logs in to Pega. The remaining portals
are available to users from either the Operator menu or the Launch menu, depending on the portal.

198
©2018 Pegasystems
Changing the logo image in a user portal
To replace the logo image in a composite portal, such as the Case Worker or Case Manager portals, you
create a binary file record for the logo image, then update the portal header to use the correct logo
image.

Create a binary file rule for the logo image

1. In the Designer Studio header, select +Create > Technical > Binary File to create a binary file rule
for the image.
2. In the Label field, enter a short description of the record to use as the file name.
3. In the App Name (Directory) field, enter the server directory used for images. In most cases, the
server directory is webdb.
4. In the File Type (extension) field, enter the file extension for the image, such as PNG.
Tip: Use a PNG or GIF image if part of the logo is to be transparent.
5. Click Create and open to open the binary file record.
6. On the File tab, click Upload file to open the Upload file modal dialog.
7. In the Upload file modal dialog, browse to and select the image file.
8. Click Upload file to close the dialog and upload the image file.
9. Click Save to complete the configuration of the binary file record.

Update the portal header to use the logo image

1. From Designer Studio, use the Launch menu to open the relevant portal.
2. Use Live UI to identify the section used in the portal header. Standard Pega portals use the section
pyPortalHeader to display the Pega 7 logo.
3. Save a copy of the section to the appropriate ruleset in your application.
Note: Select a ruleset that matches the scope of the image. For example, for a company logo, save
the header to an organization ruleset to reuse the customized header across all applications in the
organization.
4. Locate the cell containing the image, and open the Cell properties panel. For the standard
pyPortalHeader section, the cell containing the logo image is the blank cell to the left of the Case
Manager cell.
5. In the Cell properties panel, in the Image field, enter the name of the binary file record you created
for your logo image, in the format [directory name]/[binary record name].[file type]. For the Pega 7
logo displayed in the standard pyPortalHeader section, the image name is webwb/pega-7-logo.svg.
6. In the Image size field, select Auto.
7. Click Submit to update the logo used in the header section.
8. Click Save to complete your configuration.

199
©2018 Pegasystems
 Designing a mobile-ready application
Introduction to designing a mobile-ready
application
Applications are accessed by desktops, laptops, tablets, phones, or other devices. When creating an
application, you need to consider that users will access the application from both traditional and
mobile devices.
After this lesson, you should be able to:
l Identify the design approaches that support a mobile ready application
l Incorporate mobile-specific features into an application
l Configure an application to support mobile users

200
©2018 Pegasystems
Mobile design approaches
Many applications are required to run on mobile devices such as tablets or phones, in addition to
desktop and laptop computers. When the application you are developing will run on multiple devices,
you must consider elements such as screen size, font size, and control position for your user interface.
When it comes to mobile-ready controls, layouts, and other user interface components there is no such
thing as mobile-only in Pega. The advantage of Pega is that all the controls are responsive. You build a
Pega application once and it works on all devices, and seamlessly adapts the user interface.
Mobile applications follow the same core user interface principles as other Pega applications. However,
the designer and developer of the application must be aware that the user interface may be accessed
on a mobile device. Follow these guidelines when building applications that are mobile ready.

Keep the user interface simple

Highlight the most important part of the screen by placing the important information in a section as
visible. If there is supporting information, or less critical information that needs to be displayed,
consider hiding it unless the user asks for the information. This can be done by putting less critical
information under the most important content. Another technique you can use is progressive
disclosure, such as using collapsible sections, menus, or some other paradigm.

Setting widths in percent (%)

When you are designing for mobile applications, avoid using pixels on layout formats. Using
percentages enables the layout to automatically adjust for different screen resolutions. Using a fixed
width in pixels has the risk of injecting a horizontal scroll bars on a smaller device.

User controls
Pega 7 comes with a wide repository of user controls. Always use out-of-the-box auto-generated
controls. These are designed to work on all browsers and devices. They also have mobile specific
configurations. For example, you can configure a date control to have a native rendering when on a
mobile device. Set the data type of the property carefully so that the correct keypad choice appears
(number, alphabetic).

201
©2018 Pegasystems
Design the application with Tap in mind
When using a mobile device, users may find buttons easy to tap, but not links. Many people find
clicking a mouse easier than tapping a high pixel count touch screen. Ensure that actionable
components are easy to tap. Generally, a tap target should be a minimum of 44 x 44 pixels. You can use
layout level events and actions to help with that.
Events are configured to occur on a specific user action, such as navigating a menu using the mouse
movements. This is harder to do on mobile devices but can be done by redesigning the menus to work
when a user taps the screen. Use a Collapsible navigation menu to make this easier.

Designing layouts
A layout group is another key feature that helps when displaying layouts such as tabs, accordions, or
stacked layouts depending on the screen size. Layout groups are formatted in the skin rule using
responsive breakpoints to switch to a specific layout based on the resolution size. For example, you can
see a layout change where you have a two column layout (like an inline grid double) responsively
change to a one column layout (like stacked). The one column layout has better readability and
usability on small screens.

Grids
Grids are great for displaying columnar data. However, grids do not work well on a mobile device when
there are more than a couple of columns. Too many columns can be confusing to users trying to
process information off-screen. If you have a grid with a lot of columns, identify the columns that are
less important. Then identify the most important columns. Mark the columns in the grid as primary,

202
©2018 Pegasystems
secondary, and other. The grid layout uses this information to adjust when displayed on a mobile
device using responsive specifications. As the user resizes the screen or views the application on a
mobile device, the user sees the primary column and only the other columns if there is room.
When you have a requirement to show a list, use a repeating dynamic layout instead of a grid. The
repeating dynamic layout is more flexible than a grid, especially on a mobile device. Repeating
dynamic layouts automatically adjusts the layout elements with respect to the screen size. This layout
helps developers when creating an interface for displaying data that can be viewed on a tablet,
monitor, or smartphone.

Sourcing controls and grids

Always use data pages as a data source regardless of whether the user interface is going to be used on
a mobile device. This is required if you are designing applications to work on a mobile device when the
device is not connected to a network, also known as offline mode. When a mobile application is in
offline mode, all work completed is stored in data pages. The data pages are then synched to your
application when the mobile device is online.

For more information about Pega's offline capabilities, see the PDN article Offline Mobility.

Testing
Test the application on actual devices. Never rely exclusively on device emulators/simulators or on the
Pega Mobile Preview for testing. Testing on actual devices ensures that your application performs well,
provides the right experience, and works and behaves as you expect from a mobile application.
KNOWLEDGE CHECK

Why is it important to use the out-of-the-box user interface controls and dynamic layouts?
Using the out-of-the-box user interface controls and dynamic layouts means your application is
mobile ready without you having to do anything.

203
©2018 Pegasystems
Mobile-friendly controls
Pega provides a set of controls that you can use to make your applications mobile-friendly. You add
these controls to your application like other controls: determine the section where you want the control
to display and add the control from Designer Studio.

Signature Capture
The Signature Capture control captures a user signature, either through mouse input or through a
touch interaction on a mobile device.

When a user clicks Accept, the entered signature is saved as an attachment in the case. Entering and
accepting a signature can be repeated as many times as necessary, but only the last signature is
saved.
When a user clicks Clear, the current signature is deleted so that a new one can be entered. If a
signature has been saved as an attachment and then the user clears the signature, the signature
attachment is still part of the case.
A signature is automatically cleared when the control is resized (for example, when changing the
orientation of a mobile device).
To configure a Signature Capture control, go to the PDN article How to use the Signature Capture
control.

Address Map
The Address Map control allows users to view and interact with location
points in Google Maps from within the desktop and mobile
applications. To display locations correctly on a map, geolocation must
be active for your web browser or mobile device.
For the Address Map control to work correctly, you need to obtain a
Google API key. In a production environment, the recommendation is to
use an enterprise key since this allows for a greater number of
geocoding hits per IP each day.
To learn more about configuring the Address Map control and
obtaining a Google API key, go to the PDN article Using the Address
Map control.

204
©2018 Pegasystems
Attach Content
Add the Attach Content control to a desktop or mobile application to allow users to attach files to an
application. This control can be formatted to display as a button, link, or icon.
When the Attach Content control is used at run time in a desktop application, the default file browser
window opens.

The control also works on certain mobile browser, such as Safari on iOS and Chrome on Android
devices. In a mobile application, the actions are specific to the operating system.
On iOS devices, users can select an image file from the mobile device’s camera roll or take a photo.

On Android devices, users can select where to retrieve an image file, using a tiled list of applications —
including the device’s image gallery, Google Drive, Dropbox, and any other related file storage
application installed.
After initiating the attach process, users are prompted to attach a file. You cannot proceed until a file is
attached unless the attachment process is canceled.

205
©2018 Pegasystems
To learn more about using the Attach Content control, go to the PDN article Using the Attach Content
control.
KNOWLEDGE CHECK

How would you use an Attach control in layout to appear differently based on the type of
device with which the user accesses your application?
You do not have to do anything. Add the control to the section and it will render differently based on
the device.

206
©2018 Pegasystems
 Customizing the look and feel of an
application
Introduction to customizing the look and feel
of an application
If an application is easy to use, user adoption of it increases. Maintaining a consistent look and feel
throughout the application helps users navigate it more easily. In Pega, you maintain a consistent look
and feel using skins.
After this lesson, you should be able to:
l Describe the purpose of the skin
l Describe the components of a skin
l Update a skin to modify the user interface
l Create reusable style patterns using mixins
l Reference a style format in the application user interface

207
©2018 Pegasystems
Styling an application with skins
In any business, branding plays a vital role in presenting a uniform appearance across an application.
A consistent look and feel provides familiarity for end users as they use an application. Well-designed
formatting and styles help guide users through navigation and calls to action by applying consistent
formatting to user interface elements.
In Pega, you style your user interface by configuring a skin. This generates the CSS for the application.

Skins
A skin defines the responsive behavior and formatting, such as colors, fonts, images, and layouts used
in a Pega application. A skin generates the styling (Cascading Style Sheet) for the application. A skin
also defines the responsive breakpoints applied to dynamic layouts. Responsive breakpoints enable
your application to work on various devices, such as tablets and mobile phones.
For example, most companies have a corporate color scheme that their applications must follow. You
implement the color scheme in a skin, removing the need for architects to manually specify the color
scheme every time they use a UI element.
A skin applies formatting through the use of mixins and formats.

Mixins
A mixin defines a set of style attributes that can be reused in user interface elements. Mixins allow for
defining efficient and clean style repetitions, and an easy way to update styling. For example, you can
create a mixin that defines your corporate color scheme that is then reused for buttons, menus, and
headers. If your corporate colors change from blue to orange, you only need to update the mixin with
the new color, and any UI element that uses the mixin gets changed.

Mixins can either define a set of styles or inherit styles from another mixin. You can define four
categories of mixins, listed in the following table.

Category Description
Typography Allows you to configure anything related to text, like font, font size, or color
Background Allows you to configure background colors of elements
Border Allows you to configure borders and gradient effects
Combination Allows users to create complex mixins that incorporate multiple mixin types

208
©2018 Pegasystems
Formats
A format defines the styling of a specific UI component. A component is an element that you can style
within the skin — for example, a layout (dynamic layout), or a control (button).
You can define various style formats for each component. For example, you can define a style for all
buttons. You define style formats in the skin and reference the formats on property panels in sections,
harnesses, and controls. For example, you can define how inline grids or double grids are displayed to
the user.
Every component can have one or more formats defined. These formats are then used throughout the
application to control the appearance of the user interface. All components have a default format
called either Standard or Default that is supplied out-of-the-box.
The following table lists the four categories of components where you add formats.

Category Examples
General Modal Dialogs, Errors
Layouts Dynamic Layouts, Trees, Grids
Controls Buttons, Dropdowns, Labels
Reports List View, Column filter, Paging Bar

You configure a format by setting the properties in the format or by inheriting styles from a mixin.
When you update the mixin, any format based on the mixin is automatically updated. That instant
update and reusability is incredibly powerful when designing user interfaces. Within a format, you also
have the option to override part of the mixin. For example, define a mixin that specifies the color
scheme for a menu. One of the attributes of the menu format allows you to set the color when a menu
item is selected. You could override the mixin color when an item is selected to make it stand out from
the other menu items.

KNOWLEDGE CHECK

209
©2018 Pegasystems
 What element should you create to maintain a consistent group of styles?
Mixin

210
©2018 Pegasystems
How to customize application appearance
with skins
Skins are applied at an application level, but could also be applied to a portal. The best practice is to
reuse the application skin in any portal. However, at times you may create a custom skin for a portal.
For example, you could create a separate skin for the mobile application version. You only need to do
this if you want to present the application differently where using the responsive layouts does not give
you what you need.
The following example describes the relationship between mixins, formats, skins, and what you see
when you view the application. The example uses the Attach New link — this adds an attachment to a
case. You configure a link using a Link Control. One of the configuration options of a Link Control is to
specify a format for the link. In this example, the Link Control specifies the Simple format.

Every application defines a skin used for the UI. The formats are defined in the skin. In our example,
the Link Control uses the Simple format — that is, the styles defined in that format determine how the
link is rendered. For this example, the text style for Normal Text is set to use a mixin named Link.

Finally, the styles of the mixin are loaded. In our example, the Link mixin defines the font color and font
size for the text in the link.

Notes: There are other properties for both the Simple format and the Link mixin. The example
discusses a subset of the overall properties.

When creating a skin to customize the user interface, you need to answer the following questions:

211
©2018 Pegasystems
l Will you inherit styles from another skin?
l Can you inherit styles from existing mixins?

Skin Inheritance
The first decision when creating a skin is to determine if a skin that you can inherit a set of base styles
from already exists. This is known as skin inheritance.

Notes: Applications should use inheritance wherever possible. The application that you work on
should either inherit from one of the base Pega skins or a corporate skin your company has already
created.
Skin inheritance allows a skin to inherit formats and mixins from a parent skin. The parent skin defines
formats and mixins that the dependent skin can use as is or update them in a new mixin or format.
When a format on the parent skin is modified, the dependent skin automatically inherits those changes
unless the format is overridden in the dependent skin.
The advantage of skin inheritance is that you can create an enterprise-wide layering of styles. In the
following example, U+ bank (a fictional bank) uses a corporate base skin that defines a color scheme of
orange and square-shaped buttons. The financial services application for U+ is branded using green.
The financial services application would inherit from the corporate base skin and then update the
buttons to use green. Then, in a loan application may be a requirement to use rounded corners on a
button. This time, you inherit from the financial services skin and update the borders for buttons to
use rounded corners.

Another benefit of layering your skins through inheritance is that if a change is made, all skins that
inherit from that skin get the changes. In the previous example, if the financial services application
color scheme changes to purple, you can update the button color in the financial services skin. As a
result, both the financial services and loan applications have purple buttons.

Mixin Inheritance
Mixins should be the first point of customization when customizing the look and feel of an application
because they ensure that you maximize the reuse of styling. Formats then apply the style templates
created in a mixin to render a UI component.

212
©2018 Pegasystems
Like skins, mixins can also inherit from other mixins. A new mixin should be created when a new
meaning for the style is needed. For example, you may create a generic notification style in a mixin,
and then create a new mixin that inherits from the notification mixin for errors.

As with skin inheritance, using inheritance with mixins provides a layering effect where, if you change
part of a style in a base skin, the change modifies any mixins that inherit from it.

213
©2018 Pegasystems
Controlling application appearance with a
skin
Skins are used to create a consistent look and feel in your application. Within a skin, you configure the
formats and mixins used by the UI components in the application.

Notes: This procedure demonstrates how to add a new Typography mixin. However, the procedure
is the same for whatever type of mixin yow want to create. Each mixin type has its own
configuration properties.

Accessing the application skin

1. In Designer Studio, on the Application menu, click Open Application Skin.

2. Click Inheritance to update the inheritance of your application's skin (if required).

Creating a mixin
1. In your application skin, click Mixins.
2. On the My Mixins tab, click Create new mixin for the type of mixin you need to create. For
example, under Typography, click Create new mixin to create a typography mixin.

214
©2018 Pegasystems
 Notes: This procedure walks through the process of creating a Topography mixin.
3. In the Mixin name field, enter a name for your mixin, such as MyTypographyMixin.
4. In the Mixin usage annotation field, enter a description of the purpose of the mixin.
5. Click Submit.
6. Customize the mixin by specifying the style attributes. For example, define the mixin to render text
in red using the Courier New font at 10px.

215
©2018 Pegasystems
7. Click Save.

Using a mixin in a format

1. In the application's skin, click Component styles.
2. Click the slide out menu and select the format to modify. For example, from the slide out menu,
select Links to update the format for links.

Notes: This procedure updates the Link format.

3. Select the format to configure, such as the Standard format.
4. Click override it to update the Standard link format to your skin from the inherited skin.
Notes: Alternatively, you could create a new Standard format in your format. However, as a best
practice, inherit from the parent skin wherever you can.

216
©2018 Pegasystems
5. Expand the style property to update it. Select the mixin to specify the style. For example, choose the
myTopographyMixin to update the Normal Text.

6. Click Save.
7. Click Check in.

Applying a format to a control

1. In any section, open a Link control from your application.
2. Click Presentation.

217
©2018 Pegasystems
3. Update the Control format with the format used for this link.

4. Click Save.

218
©2018 Pegasystems
REPORT DESIGN

219
©2018 Pegasystems
 Creating reports that combine data
from multiple tables
Introduction to creating reports that
combine data from multiple classes
In this lesson, you learn three techniques to create a report that references data from multiple classes:
combining data in a report by creating subreports, configuring class joins, and referencing reusable
association rules.
After this lesson, you should be able to:
l Describe how Pega data can be stored in multiple database tables
l Describe the relationship of class mappings to database tables
l Explain how associations and joins combine data in different tables for reporting
l Explain how subreports combine data in different tables for reporting
l Use associations and joins to combine data from different database tables in a report
l Configure a report to incorporate data from a subreport
l Create a report that uses a class join

220
©2018 Pegasystems
Data storage in Pega
Pega saves data across multiple database tables when a case is processed. The system uses Pega
classes to organize and store the data in the appropriate table. When you create reports, the Pega
reporting tool uses the Pega class organization to find and retrieve information from these tables.
Efficient data organization and access enables the organization to generate reports that support key
strategic decisions.
For example, managers may want to know which customer service representatives (CSRs) resolved the
most cases during the past three quarters. The report requires you combine case information and
historical processing information. This information may be stored in separate tables.
The following video highlights how Pega's flexible data model helps generate information immediately
to suit reporting requirements.
KNOWLEDGE CHECK

How does the Pega reporting tool find and retrieve data from the appropriate table?
The tool uses Pega classes to find the table.

221
©2018 Pegasystems
Class mappings and database tables
Any Pega class that has instances, such as case types, can be mapped to a database table. For example,
when users create cases, the system assigns the case an ID and saves the value as an individual row in
a database table. When you generate reports, you are retrieving data from rows in database tables.
Reports use class mappings to locate the data from one or more database tables.
When designing reports, you need to know which table has the data and how the data is mapped. For
example, you may need to create a report that contains information about Candidate cases. These
records are instances in the case work class. In the same report, you may also want to include
workbasket information about each candidate case. Workbasket records are instances in a workbasket
class. The information for each type of information is stored in separate tables. When you combine the
information in a report, you use class names to identify in which tables the information is stored.

Records used for mapping classes to tables

Pega uses two records to identify the database table the class is mapped to: Database and Database
Table.
l A Database record identifies how Pega connects to a specific database for the named database. The
record contains connection information so Pega can access the database. The record establishes an
alias that can be referenced elsewhere, such as a database table record. Database records can be
configured to use either JNDI or JDBC url for the database connection. By default, Pega uses the
following standard databases in a database record:

222
©2018 Pegasystems
 PegaRULES maps to a database where all Pega rules and system data are stored.
PegaDATA maps to a database where data and work instances are saved.
l A Database Table record identifies a specific table in a specific database, and specifies the
corresponding Pega class. Pega uses this record to identify which table to write case data when a
user creates or updates a case.
KNOWLEDGE CHECK

How does Pega map classes to database tables?

Pega uses two records — a Database record and a Database Table record — to map classes to
database tables.

Mapping multiple classes to a single table

In some situations, you want to have multiple classes store data in the same table. For example, you
might have an application with three case types such as Candidate, Onboarding, and Benefits
Enrollment, and you want to report on the work statuses of all cases in the application. Rather than
create a database table for each case type, you can designate a class as a class group (also referred to
as a work pool). Class groups cause the system to store instances of similar or related case types
together in a single database table. If you create a report in a specific case type such as Candidate,
your report returns only records in the case type. If you create a report for the class group, the report
returns all instances in the classes that belong to the class group.
In Designer Studio, the mappings are displayed in the Database Class Mappings landing page. The
following example shows the work classes that map to the class group database table pc_TGB_HRApps_
Work.

Three commonly used report types

You commonly generate three types of reports: work, assignment, and history. Each type of report uses
properties in classes mapped to a variety of data tables.

Work reports
When a case is created, Pega uses standard properties in the Work- base class to define each case.
This Work- base class includes properties that describe the following:
l A case identifier (pyID), the work parties participating in a case (pyWorkParty)
l The customer identifier such as an account number (pyCustomer)
l The work status of the case (pyStatusWork)

223
©2018 Pegasystems
For descriptions of the important standard Work- properties used in case-based reports, see the help
topic Standard properties in the Work- base class.
Standard properties that support subcase processing can be found in the Work-Cover- class. For
descriptions of those properties, see the help topic Standard properties in the Work-Cover- class.
Standard properties in the @baseclass class are available for every case when it is created. The most
important property is pzInsKey. Pega uses this property to internally identify each case. A subcase also
has a property named pxCoverInsKey that identifies the parent case.
For descriptions of the standard properties see the help topic Standard properties in the @baseclass
class.

Assignment reports
Cases requiring user interaction are assigned to a user during processing. Each time a case is
assigned, Pega creates an assignment object. When the case is completed and advances to the next
assignment, Pega creates another object. If the assignment is routed to an operator, Pega saves the
object to the database table named pc_assign_worklist. If the assignment is routed to a workbasket,
Pega saves the object in a database table named pc_assign_workbasket.
Some commonly used properties that are specific to assignments include the operator who has the
assignment (pxAssignedOperatorID) or the name of the flow rule for the assignment (pxFlowName).
When creating assignment reports, you often use pxRefObjectKey — this is mapped to pzInsKey. The
pxRefObjectKey property allows you to relate the assignment to the case.
For descriptions of many standard properties used in assignment reports, see the help topic Standard
properties in the Assign- base class.

History reports
When a case is being processed, the system automatically captures audit trail data in the history
classes. The classes are mapped to the History database tables where the data is saved. For example,
the history class History-TGB-HRApps-Work is mapped to pc_History-TGB-HRApps-Work.
History reports use properties in the History- and History-Work- classes. These properties include
pyHistory type (identifies the event that caused the history event), or pyPerformer (identifies the
operator who completed the event recorded in the history instance).
Properties in history classes can be used to design performance-based reports. For example, you can
use pxTaskElapsedTime to report the total time spent on an assignment. If an assignment is routed to
multiple users, you can use pyPerformTaskTime to report on the total time spent by all users. If
pyPerformTaskTime is significantly lower than pxTaskElapsedTime, then the assignment has been idle for
a long time.
For descriptions of the properties in the History- and History-Work classes, see the help topics
Standard properties in the History- class and Standard properties in the History-Work- class.
For more information about using the statistics for performance reports, see the help topic Assignment
statistics.
KNOWLEDGE CHECK

224
©2018 Pegasystems
 You create a report that shows how quickly cases were processed in a specific assignment.
Which classes contain the standard properties you use in your report?
History-Work- and History- classes

225
©2018 Pegasystems
How to combine classes using joins and
associations
You can relate properties in multiple database tables or classes to combine data in a single report. The
following examples show you how to use properties to make relationships between classes or tables.
l Use case and subcase relationships to show subcase data along with the parent case data. For
example, assume you want to create a report that lists the purchase orders in a purchase request.
You match the case identifier in the parent purchase order class to the case identifier in the child
purchase request class.
l Use case and assignment relationships to show how the system processes assignments for a
specific case or a subcase. For example, assume you want to show the operators working on specific
cases. You match the operator identifier in the case database table with the operator ID column in
the assignment table.
l Use case and history relationships to monitor performance. For example, assume you want to show
the total amount of time required to resolve specific cases. You match the case identifier in the case
data table with the case identifier in the history table.
You create class or database table relationships in a report definition. You do not specify database
tables to define joins. You can either configure class joins or you can reference association rules.

Class joins
When you build a class relationship in a report definition, you configure a class join. For example,
assume you want a report that identifies the current assignment and operator working on each
candidate case. The candidate information is in the Candidate case type. The assignment information
is in the assignment workbasket class. You would create a report definition in the Candidate class and
configure a class join to the assignment-workbasket class. In the report definition, you would first
specify the Assignment-Workbasket class as the class you want to join to your report. You would then
specify a filter that matches key values in records for both classes. For example, you would match the
candidate case key value pzInsKey to the workbasket assignment key value pzRefObjectKey. In this way,
the report can correctly match, for each case, the records in both classes.

You follow these basic steps to create a class join:

l Determine the class to which you are joining.
l Create a prefix that in combination with the class name serves as an alias for the joined class.

226
©2018 Pegasystems
l Decide whether you want to include or exclude instances that do not match.
l Create a filter that describes how you relate the classes.
Note: In the report definition form, you specify the class as the primary join. If this work type is
derived from Work-, determine whether the join is to an implementation class or to a framework class.
This ensures that you are joining to the correct data set.

Class join settings

On the Data Access tab on a report definition form, in the Class name field you specify the class you
are joining. For each class, in the Prefix field you enter a text prefix. The prefix combined with the
class name serves as an alias for the joined class and its properties. For example, to join to a work class
that describes benefits enrollment cases, you might use the prefix BE as shown in the following image.

When you add properties to columns in your report, the prefix helps you identify the properties in the
joined class.

In the Type field, you specify how you want the system to join the data by selecting one of the following
options:

Type Description
Only include matching rows To only include instances in each class that have
a matching instance in the other class (referred
to in database terms as an inner join)

227
©2018 Pegasystems
 Type Description
Select Include all rows in <class> To include all qualifying instances of the Applies
To class of the rule, even if there is no match
found in the joined (prefix) class (referred to in
database terms as an outer join)
Select Include all rows in <prefix> To include all qualifying instances of the joined
(prefix) class, even if there is no match found in
the Applies To class (referred to in database
terms as an outer join)

Filter conditions
You create a filter condition that defines the relationship between the classes. The filter uses one or
more properties to establish the relationship. Consider the Benefits Enrollment class join to the
Candidate class. You would create a filter that matches the .pxCoverInsKey property in the Benefits
Enrollment class to the .pzInsKey property in the Candidate class.

Note: You cannot join to a class in a different database than the Applies To class of the report. The
Column property must be an exposed column. You can use the Optimization tool to expose columns.
For more information about the tool, see the Help topic Property optimization using the Property
Optimization tool.
For descriptions of the fields you use when defining a class join, see the help topic Report definition
access tab.

Association rules
You use association rules to join multiple classes. Unlike a class join (unique to each report),
associations can be reused in any report. Managers can also use associations when they create reports
in the Case Manager portal.
For example, assume you want to combine records in the Assign-WorkBasket class with records in work
classes. You use the standard WorkBasket Assignment (pxWorkbasketAssignments) association rule to
join the classes.
Note: Pega provides a set of standard association rules. You can use these rules for many class joins.
For example, standard association rules allow you to join work to assignment classes or to history
classes. For a list of standard association rules, see the Help topic Standard Association rules.

228
©2018 Pegasystems
When you add a column, you specify the association rule class name as a prefix, then select the
properties in the class.

When you add the association rule prefix, it appears on the Data Access tab in the Associations
section.
For information about creating your own association rules, see the Community article When and how
to create an association rule to support reporting.
KNOWLEDGE CHECK

When configuring a class join, how do you specify a property that defines the relationship
between the primary and joined classes?
Create a filter condition

Creating class joins and associations in

reports
You can report on records in multiple classes mapped to one or more data tables. To create these
reports, in a report definition you can reference an association rule or configure a class join.

Referencing an association rule

After you create a report definition in the class you want to report on, reference an association rule to
join another class.
1. Open your report definition.
2. In the Edit columns section, in the Column source and Column name fields, enter the name of
the association rule you want to reference. The system uses the prefix for the properties you want

229
©2018 Pegasystems
 to include.
The following example shows the pxWorkbasketAssignments association rule prefix and properties.

3. Click Save to save your reference to the association rule. When you add a column that uses an
association, the system automatically references the association. The Associations field on the Data
Access tab displays the association.

Configuring a class join

After you have created a report definition in the class you want to report on, create a class join to
establish a relationship to instances of another class.
1. Open your report definition.
2. On the report definition form, open the Data Access tab.
3. In the Class joins section, click Add class join to add a row.
4. In the Prefix field, enter a prefix for the class to join to the report definition. Use this prefix to
reference properties in the class.
5. In the Class name field, enter the class to join to the report class. The form looks like the following
image.

6. At the end of the row, click Edit conditions. The system displays the Enter filter conditions dialog.
7. In the Column field, select a property within the joined class.

230
©2018 Pegasystems
 8. In the Value field, enter a property in the report definition's Applies To class.

9. Click Submit to save your filter condition and close the Enter filter conditions dialog.
10. Open the Query tab.
11. In the Edit columns section, enter Column source and Column name values.
Note: Use the class prefix to find properties in the joined class you want to include in the report.
When you are done, the report definition looks like the following image.

12. Click Save to save the join configuration in your report definition.

231
©2018 Pegasystems
How to combine data from different classes
using a subreport
Subreports enable you to reference results from any report definition in a main report. A report
definition used as a subreport can be run like any other report.
Note: Consider subreports as a way of combining data using IN, HAVING, and WITH clauses.
Subreports can be defined in classes different from the main report. You can access data in different
classes similar to the way you would use a class join or an association.
You commonly use subreports to satisfy complex reporting requirements. For instance, you can use
subreports to filter results. This approach allows you to include or exclude data. You can also use
subreports to display aggregate calculations on specific rows in a main report.
You use two different methods to create a subreport: join filters or aggregation.

Using join filters to create a subreport

Assume you want to display the task information for each purchase request recently updated by each
operator.
Do the following things to create the report:
l Create a subreport for purchase requests that retrieves the most recent update date by update
operator.
l On the main report in the Query tab, add columns for the requested data for each case and specify
the subreport you want to reference.
l On the main report's Data Access tab, add the subreport.
l Create a join filter condition for the subreport. The filter defines how you want to join the subreport
data to the main report. As shown in the following example, the subreport Update Operator column
is matched to the update operator value (.pxUpdateOperator) in the main report.

l On the Design tab, add a filter condition so that the update date value is equal to the update date
value in the subreport.
When you run the report, it shows, for each operator, information about the purchase request the
operator most recently updated. For each case, the report displays the update date and time retrieved
from the subreport.

232
©2018 Pegasystems
The procedure for creating the previous example is described in the Community article When and How
to Use subreports in a Report Definition. See Use Case 2.
Note: The examples in the Community article were created in Pega 6.2. The styles on the rule forms
have been upgraded in Pega 7. However, the fields and functions are still applicable.

Using aggregation to create a subreport

You can use subreports to display aggregate calculations on specific rows. For example, assume you
want to list the managers in the Engineering division who have more than ten direct reports.
You would do the following things to create the report:
l Create a subreport that shows the managers who have direct reports, and how many they have. You
use filter conditions to limit the data to managers who are part of the Engineering division and
report directly to someone.
l On main report's Data Access tab, add the subreport.
l Create a join filter condition to join data from the subreport to the main report where the value in
the subreport's operator column matches the value in the operator column in the main report.
l Create a filter condition to use only data from the subreport where the number of reports-to
instances is greater than ten.
When you run the report, it displays managers in the Engineering divisions who have more than ten
direct reports.

233
©2018 Pegasystems
The procedure for creating the previous example is described in the Community article When and How
to Use sub-reports in a Report Definition. See Use Case 3.
For descriptions of the fields you use to configure a subreport, see the Subreports section in the Help
topic Report Definition Data Access tab.
Subreports can be configured to support many types of report requirements. For example, you may
wan to list the average number of direct reports for the managers in a specific division or list the
operators who have not updated work items of a specific type within the past week. To see more use
cases and design procedures, refer to the Community article When and How to Use sub-reports in a
Report Definition.
KNOWLEDGE CHECK

How can you use a subreport to list the operators who have not updated cases of a specific
case type within the past week?
Use the subreport as a filter, comparing with a list of all operators and removing all entries where
there is a match between the two reports.

234
©2018 Pegasystems
DATA MANAGEMENT

235
©2018 Pegasystems
Exposing an application with a service
Introduction to exposing an application with
a service
In this lesson, you learn how to use web services to expose application functionality. You learn how to
identify an application function and use the Service Wizard to wrap the function in a SOAP framework.
After this lesson, you should be able to:
l Describe the components of a service
l Explain how to create a service with the Service Wizard
l Explain how to add error handling to a service
l Create a SOAP service using the Service Wizard
l Test a SOAP service

236
©2018 Pegasystems
How to expose an application as a service
The two most common ways to expose your application as a service is either to create a web service or
to leverage the Pega API.
Conceptually, these two options work the same way: a request is made to a URL, and a response is
returned. The difference is how you communicate with the service.

Leverage the Pega API

The Pega API provides a standard set of services that includes new case creation, assignment
processing, and access to data pages. These built-in REST/JSON services enable the rapid
implementation of Pega-powered mobile and client applications.

You can call any of the Pega API services by using standard HTTP methods (for example, GET, POST, or
PUT). Refer to the Pega API resources page in Designer Studio (click Resources > Pega API) to see
details of the request and response data requirements. This documentation is also available in JSON
format in the Docs API (GET/docs).

Resource Description
Assignment Provides the ability to obtain a list of assignments for a user, obtain the details of any
API specific assignment, and perform an assignment action
Authenticate Allows you to verify user credentials
API
Cases API Provides the ability to obtain a list of cases for a user, create a new case, obtain case
details, and update a specific case
Casetypes Provides the ability to obtain a list of case types for the authenticated user
API
Data API Facilitates the process of obtaining the contents of a data page and obtaining the
metadata for a specific data page
Docs API Provides access to the complete documentation for the Pega API

You can learn more about the Pega API on Pega Community at Pega API for the Pega 7 Platform.
You can practice using the Pega API on Pega Community at Getting Started with the Pega API.

237
©2018 Pegasystems
Create a SOAP service
When you have a requirement to implement a SOAP web service to expose your application to other
applications, you do this by creating a service. SOAP web services communicate using the SOAP
protocol and pass XML messages from one application to another. Your application needs to convert
that XML message to Pega objects to process them and then convert those Pega objects back to XML
after the processing is complete.

A SOAP service uses a combination of rules to process a request. The rules you use are:

Rule Description
Service An activity that performs the steps of what you want done in the service
activity
XML Parser Map data from an XML message into clipboard property values
XML Assembles and sends an XML document in an email message, a SOAP message, a file,
Stream or other types of messages
Service Groups one or more service rules that are designed to be developed, tested, and
Package deployed together

These rules work together to process a request and send a response back to another application. The
following diagram shows how Pega processes a service request.

238
©2018 Pegasystems
 1. A client application sends a request to your application.
2. The service listener listens for incoming requests. This functionality is provided by either the Web
Server, Application Server, or Pega Listener.
3. The service listener receives the request and instantiates the Service API to provide communication
with Pega. Then, via the Service API, control is handed to Pega.
4. Pega looks up the service package and related service rule, using the access group that is specified
in the service package.
5. Pega then establishes the service requestor, and optionally performs authentication based on
security credentials that are passed in the request. Once authenticated, service processing
continues using the authenticated user’s access group, not the access group that is contained in the
service package.
6. The request is mapped, using the instance of an XML Parser rule, onto the clipboard according to
the specifications contained in the service rule.
7. Control is passed to the service activity, which provides the logic for the service.
8. Using the XML Parser rule, the service rule maps the clipboard data to form the response data.
9. The service listener receives the response from the Service API.
10. The service listener sends the response back to the application that made the request.
11. The client application receives the request.

239
©2018 Pegasystems
KNOWLEDGE CHECK

What is the purpose of a service?

Services are used to allow other applications to access to your application.

240
©2018 Pegasystems
Creating a SOAP service using the Service
Wizard
You run the Service Wizard to create all the records needed to expose your application as a service.
The Service Wizard walks you through entering the settings required to create the service. The Service
Wizard does not create XML mappings for inherited properties, so you must add those properties as
needed.

Run the Service Wizard

1. Select Designer Studio > Integration > Services > Service Wizard to start the Service Wizard.
2. Complete the Select Service Purpose section:
a. Set the Service Purpose to Create and manage work.
b. Set the Service Type to SOAP.
c. Click Next.

Note: Create and manage work is the most common reason to create a service. You invoke an
existing service activity if you have created the activity previously. The Process input or output data
provides an empty activity that you configure to get or process the desired data. The options in the
Wizard differ based on the Service Purpose selected.
3. Complete the Provide Service Details — Select Work Properties section:

241
©2018 Pegasystems
 a. Set Work Type to TGB-HRApps-Work-Onboarding.
b. Set Flow Type to pyStartCase.
c. Select Create Work and set the Organization to TGB.
d. Click Next.

4. Click Next.
Note: The pyStartCase flow does not have any flow actions that you want to consider a service to
execute.
5. Select Use XML for data mapping to allow for list structures in the request.
Note: Only properties defined directly in the TGB-HRApps-Work-Candidate case type are displayed.
Inherited properties are not displayed and need to be added manually after the Wizard has been
completed.
6. Select the following input properties:
l .Employee.Manager
l .Employee.StartDate
Click Next to confirm the proprieties to use.
7. Set the Ruleset Name to HRApps, and set the Ruleset Version to the version in which you are
working.
8. From the Service Package Options drop-down list, select Configure a new service package, then click
Next.

242
©2018 Pegasystems
 9. Keep the default settings in the Configuration Data Records screen. Click Next.
Note: Requires authentication is selected by default. This means that you need to provide an
operator and password when you call your service.
10. The Review and Save screen displays the records that will be created by the Wizard. Click Finish to
create the records.
The final page displays the records created by the Wizard.

243
©2018 Pegasystems
Add inherited properties
1. Open the CreateNewWorkResponse XML parse rule generated by the Wizard.
2. Click Add Element to add the required input parameter that was not available for selection in the
Wizard.
3. Double-click the new property to configure it.
4. Enter a Node Name and specify the Property to map the value.

244
©2018 Pegasystems
5. Click OK to update your changes.

Test the service

1. Open the service rule.
Tip: You can access the service rule from the final screen of the Service Wizard. If you have closed
this screen, you can open the Records Explorer and navigate to Integration-Services > Service
SOAP to access it.
2. Click Actions > Run to test the service rule.
3. Select Supply SOAP request envelope to enter values for the test.
4. Update the request and enter values for each option. In the following screenshot, you see values
have been entered for Employee, SSN, and FirstName.

245
©2018 Pegasystems
5. Click Execute to test the service.
6. Your response will vary based on what you are attempting to do. If there is an error, you see a
SOAPFault exception produced.

246
©2018 Pegasystems
How to configure exception processing
Integrating with external systems can introduce additional problems such as network errors involving
firewalls, incorrect authentication or credentials, or system failures. An application that handles
exceptions properly is critical to the success of any application.
Many errors can be anticipated at design time and addressed with specific actions to help ensure a
positive customer interaction. But unexpected errors may still occur and are just as important to
address promptly.

Exception processing is critical to catch errors and exceptions during execution of a service rule so that
they can be communicated to the client application in a clean way. Best practice requires you to
configure clipboard property values to communicate service errors to the calling application.
Many service types, including SOAP, have an exceptions or faults tab where you can define what the
application does when a service error or exception is encountered. When the service encounters a
processing error and a condition evaluates to true, the application returns a defined error message to
the calling application. The following conditions are available for defining an error response message.

Condition Description
When The specified when rule returns true.
Queue If the specified when rule returns true, the request is queued and a Pega-specific SOAP
When fault that includes the queue ID of the request is returned.
Mapping An error occurs while mapping incoming data from the request message to the
Error clipboard.
Security Authentication fails.
Error
Service A valid instance of the service activity cannot be found.
Error

If the mapping, security, and service errors are not defined, the system returns standard exceptions,
such as an AuthenticationException if the supplied credentials are not valid.
For more information about configuring the Fault tab of a service, consult the help topic Service SOAP
form Completing the Faults tab.
KNOWLEDGE CHECK

247
©2018 Pegasystems
 What is the purpose of using a condition in a SOAP exception?
Conditions allow you to add a custom error message to the response.

248
©2018 Pegasystems
 Reading and writing data to the
database
Introduction to reading and writing data to a
database
Many Pega applications need to exchange data with each other as well as with external systems. In this
lesson, you learn how to use Obj- methods and Structured Query Language (SQL) connectors to read
and write data to databases.
After this lesson, you should be able to:
l Describe the use of external databases in Pega applications
l Differentiate between options for connecting to an external database
l Determine when to use Obj- methods for database integration
l Determine when to use SQL connectors for database integration
l Read and write data using activity Obj- methods
l Use symbolic keywords to navigate lists
l Connect to an external database

249
©2018 Pegasystems
The PegaRULES database
Each system stores rules, work, and other data in a Pega relational database known as the PegaRULES
database.
The PegaRULES database contains all of the permanent data for all the Pega applications. Detailed
knowledge about the database is not needed for most application tasks. Designers can create new
rules and new properties, and save data without updating the database structure. Built-in tools and
wizards help you understand how well the database is operating and where to focus efforts to tune
application performance.
As users interact with a Pega system, rows of the database are automatically created, updated, saved,
and deleted. The database includes user inputs, decisions, and the results of calculations. For example,
for a purchase order request system, as users create purchase orders, the PegaRULES database is
updated with the each new purchase order requests. Input from a single user — for example,
approving a purchase order request — causes updates to multiple tables in the PegaRULES database.
Database updates occur simultaneously (known as a transaction commit) so that PegaRULES is always
up-to-date. Internally, database updates are transmitted as Structured Query Language (SQL) queries.
Use Obj- methods to query tables present in the PegaRULES database. By default, Pega uses only the
database table name to identify tables for database queries. This can cause issues in some situations.
To handle such situations, use fully qualified table names.
For additional information
PegaRULES database overview
Default database tables (Data-Admin-DB-Table)

250
©2018 Pegasystems
External databases
Pega applications sometimes require access to data stored outside of the application. For example, an
application to provide quotes for automobile insurance policies may rely on a system of record for
customer policy data. Also, an order management application may rely on an external inventory
database.
The information in an external database is often manipulated by an application. For example, an order
management application needs to update the inventory database after a user submits an order. This
ensures that future orders reflect current inventory levels. Also, customers may update their home
mailing address for their automobile insurance policy.

To manage the data read from and written to an external database, you create an external class in your
application. An external class is a class that corresponds to a table in an external database rather
than to a table or view in the PegaRULES database.
External classes differ from other Pega classes in three ways.
l An external class cannot belong to a class group. Instead, it corresponds to a database table not
administered by Pega. Each external class should be mapped to a unique database table.
l An external class does not contain either the pzInsKey or pxObjClass properties. These properties
are used by Pega as key columns to identify rows in tables in the PegaRULES database. Instead, the
external class uses the key column specified by the database table to identify unique rows.
l An external class maps Pega properties to database columns. This mapping identifies the database
columns that correspond to the properties used in the application. You can use this mapping to
provide more meaningful names for cryptically named database columns. For example, an external
class can map the database column CustAdrHome to property .CustomerStreetAddressHome.
Note: For a class mapped to the PegaRULES database, Pega uses the name of the property record as
the database column name.
The external class allows you to operate on the data stored in the external database. For example,
properties in an external class are present on the clipboard, and you can set property values with data
transforms and declare expressions.
Assume that an office furniture purchase order form includes fields for three target property items:
chairs, desks, and lamps. You have selected rulesets and versions for the table mapping, and created a
class to map to the external table that holds inventory data for chairs, desks, and lamps. A declare
expression uses the two source properties — item cost and quantity — to calculate the target property:

251
©2018 Pegasystems
item total. The declare expression multiplies the item cost from the external database by the quantity
to calculate the item total.
KNOWLEDGE CHECK

How does an external class relate to an external database?

An external class maps the contents of the external database to properties in Pega. This allows Pega
to use the data from the external database in applications.

252
©2018 Pegasystems
Obj- methods
When you create a class mapping to an external database table, you can read from and write to the
database using activity records. Activities consist of a series of steps that represent the operations
performed when the activity runs. Each step includes a method that describes the action to perform.
Note: For information on determining when to create an activity, see the Pega Community article
Introduction to Activities. For more information on the activity methods provided for activities, see the
Help topic Methods and Instructions by Name.
When you configure an activity to read from or write to a database, you use a subset of activity
methods called Obj- methods, provided by Pega. Obj- methods operate on one or more objects, or
rows, in a database table, to open, save, and remove database records.
Tip: You can use Obj- methods to read or write class instances in the Pega database, in addition to
records in an external database.
To configure an activity for reading from or writing to an external database table, use the methods
described in this lesson.

Read from a database

The obj- Open methods are used when you want to update the object you read. Use Obj-Open or Obj-
Open-By-Handle to load an instance of a class stored in either the PegaRules database or an external
database. Obj- Open and Obj-Open-By-Handle methods create a clipboard page for the instance
opened.
Note: If you want to fetch read-only data on a Data Page use a lookup and report definition.
Use Obj-Browse to search the database, retrieve multiple records, and copy them to the clipboard as
an array of embedded pages. Use the Obj- Browse method optionally followed by the Obj- Filter
method to create a list of search results.
Use Obj-Refresh-and-Lock if the instance is already present on the clipboard as a page. Use Obj-
Refresh-and-Lock to test whether a page is current and if a lock is held. If the object is locked, Obj-
Refresh-and-Lock has no effect. However, if the object is not locked, the activity acquires a lock and
refreshes the page if it is stale.

Save to a database
Use Obj-Save saves the contents of a clipboard page to the database. Obj-Save immediately writes the
object to the database only if the WriteNow parameter is selected. If the WriteNow parameter is not
selected, the Obj-Save operation becomes a deferred save. A deferred save adds a deferred operation
to an internal list of operations to be performed on the next commit. The internal list is also known as
deferred operations list or deferred list.
Until the next commit occurs, either explicit or automatic, changes are not reflected in the database.
The benefit of this deferral is the ability to perform multiple, back-to-back saves on the same object
instance. Pega combines the updates into a single cumulative update at the time of commit. This
decreases the interval of time in which locks are held within the database and maximizes concurrency
within the application.

253
©2018 Pegasystems
Caution: Specifying WriteNow defeats all the benefits of the deferred save feature. Avoid enabling the
WriteNow option unless absolutely necessary. Enabling this option causes the activity to perform a
commit operation, and this commits any deferred operations. If the deferred operation also writes the
same record, Pega performs the current activity step first, then performs the deferred operations. This
may overwrite the result of the Obj-Save operation.
A valid reason to perform a WriteNow is the need to immediately reread this instance before issuing a
commit. Using this parameter can cause incorrect information if you do not use proper locking and
error checking in your configuration. For more information, see the Pega Community article When to
set the WriteNow parameter in the Obj-Sav and Obj-Delete methods.

Delete a database record

Use Obj-Delete or Obj-Delete-By-Handle to remove an instance from the database. Obj-Delete
deletes a database row based on the contents of a clipboard page, or marks it for later deletion with
the Commit method. Use Obj- Delete-By-Handle to delete an instance identified by its handle.

Cancel or rollback operations

Use Obj-Save-Cancel to undo the last change. Obj-Save-Cancel cancels the most recent uncommitted
Obj-Save method so that the instance is not written as part of a later Commit operation. You can also
use this method to undo an Obj-Delete that has not yet been committed. The page identified in the
most recent Obj-Save or Obj-Delete method is removed from the set of pages pending a Commit
method. When a later Commit method executes, this page is not included in those committed. This
method updates the pxMethodStatus property.
Use the Rollback method to cancel or withdraw any previous uncommitted changes to the PegaRULES
database (and to external databases accessed from an external class) from the current Thread. When
you use the Rollback method, all pending Obj-Save and Obj-Delete methods are canceled. As a result,
all uncommitted database operations are withdrawn. If an instance is locked and the
ReleaseOnCommit box was selected, the lock is released. Locks on instances where the
ReleaseOnCommit box was not selected are retained.
Important: Using the Rollback method cancels all uncommitted Obj-Save and Obj-Delete operations,
not only the most recent one.
KNOWLEDGE CHECK

_____________________ and ________________________ methods create a clipboard page for the

instance opened.
Obj- Open and Obj- Open-By-Handle

254
©2018 Pegasystems
How to connect to an external database
Pega applications frequently need to exchange data with external systems. For example, an application
requirement may be to respond to requests for order status updates. Order status data is stored in an
external system of record database. The Pega application has to integrate with the SoR database to
retrieve and modify data hosted outside of the Pega 7 system.
Pega provides the External Database Table Class Mapping wizard to guide you through the process of
connecting to an external database.

Select a connection method

If your application performs simple SQL statements against a single external database table, use the
External Database Table Class Mapping wizard to create an external class mapping. The External
Database Table Class Mapping wizard maps the database contents to an external class in your
application. Read and write data to the database using Obj- methods in activities.
If your application performs more complex SQL statements such as joins or stored procedures against
external database tables, configure Connect SQL rules.
Tip: In certain situations, you may need to use a combination of Obj-methods and Connect SQL rules.
For example, you may need to configure a complex search using an SQL Connector; the remaining
operations can be performed with Obj-methods.

Connect to the external database

Database table mapping and the SQL connector both require you to perform three steps:
l Register the external database.
l Identify the database table containing the needed data.
l Map the database table columns to application data elements.

Register the external database

Before you can read from or write to a database, you must register it with the Pega server. To register a
database in Pega, you create a Database record. For example, if the system of record for customer data
is an external database, you create a database record named Customer. In a Pega application, you
reference the database record to connect to the external database.

255
©2018 Pegasystems
A database record allows you to identify connection information for either the Pega database or an
external database. The use JDBC Connection pool and use configuration in preferences options are used
for connecting to the Pega database.
Note: Database records can be found in the Records Explorer, under SysAdmin > Database.
The database record defines an alias for the database, and contains the information needed to
connect to the database. Configuring the database record allows you to then connect to the database
using either the Database Table Class Mapping wizard or the SQL connector. The following example
shows one possible configuration to an external database.

When configuring a database record, consider how you plan to connect to the database. For external
databases, select the use JDBC URL listed below option. This option allows you to specify the database
URL and authentication information needed for Pega to connect to the database. For more information
on providing authentication information, see the Help topic Completing the database tab.
Important: Before you configure a connection to an external database, confirm with a system
administrator that the appropriate JDBC library for the database has been installed on the Pega
server.
To test your connection to the external database, click Test connection. This test allows you to verify
that the information you entered leads to a connection. Pega tests the configuration and displays a
status page indicating whether the test was successful or not.
KNOWLEDGE CHECK

What is the purpose of a database record?

A database record specifies the connection information needed to establish a link to a database,
such as a system of record.

Identify the database table containing the needed data

Once you identify the database that contains the required data, you identify the table that contains the
relevant data. To link a class to a database table, you create a Database Table record.

256
©2018 Pegasystems
Note: Database table records can be found in the Records Explorer, under SysAdmin > Database
Table.
To configure a database table record, you specify the database to connect to and the table to read from
or write to. In the previous example, Pega instances of the data class TGB-Data-ABARouting Numbers are
read from and written to the table ach_lookup.
Both the External Database Table Class Mapping wizard and the Connector and Metadata wizard
create a database table record for you. In either wizard, you enter or select the database name and
Pega queries the database for a list of tables for you to choose from. If necessary, enter the name of
the schema that contains the table.
To test your connection to the database table, click Test connection. Pega tests the configuration and
displays a status page indicating whether the test was successful or not.
Note: Creating a Database Table record for every concrete class used in your application is not
necessary. For classes written to the Pega database, such as the classes that represent case types,
Pega uses pattern inheritance and class groups to locate the appropriate Database Table instance for
an object. If none is found, Pega uses the table pr_other as default.
KNOWLEDGE CHECK

What is the purpose of a database table record?

257
©2018 Pegasystems
A database table record maps instances of a class to a database table.

Map the database table columns to application data elements

After you identify the database table, you identify the columns in the table that contain the data used
by your application. Both the External Database Table Class Mapping wizard and the Connector and
Metadata wizard use your selections to create an external class with properties mapped to the
columns you select.
Once you complete either wizard, you can reference the properties in the external class in your
application.

258
©2018 Pegasystems
How to use symbolic indexes to reference
lists
Pega provides a set of symbolic indexes to access items in a page list without using an explicit index
number. For information about symbolic indexes, refer to Symbolic indexes -
APPEND, CURRENT, INSERT, LAST and PREPEND in the PDN articles Expressions - How to reference
parts of aggregate properties.
When data is read into a Pega application, the data may include a set of records recorded in a page
list. Pega needs to navigate the entries in the list to locate a specific item. Often this is done by
iterating through the list to find an item, or appending an item to the list using symbolic keywords.
For example, consider the vehicle inventory for an automobile dealer. When a salesperson sells a
vehicle, it must be removed from inventory. In order to remove the vehicle, you need to know which
entry in the list corresponds to it. Otherwise, you may remove the wrong vehicle from inventory.
You can configure an iteration that performs a repeated computation over a collection, such as all the
elements in a Page List property. In the example, you need to iterate through the list to identify a
specific item in the list. When you add a loop to a data transform or an activity, you can use the
<CURRENT> index keyword to read the current item as the loop iterates. Or you can use <INSERT>
index keyword to write a new item at the current index and push the remaining items down in the list.
For more information about entering loops, refer to Completing the Steps tab - Entering loops.

Read and write list items using an activity

In Pega, you may use a data transform or an activity to iterate over a list. For instructions on
configuring an iteration in an activity step, see the Help topic Activity form — Completing the Steps tab
— Entering loops.

Read and write list items using a data transform

You can use a data transform to iterate over a data page that uses a list structure. To review a sample
procedure, see Iterating over a page list in a data transform using Pega 7.
Note: You cannot use a data transform to write to a database. See Apply-Data Transform method.

Use symbolic indexes

If you know the index number in a list, you can add an item sequentially. If you do not know the index
number, use symbolic indexes to iterate over a list.
To write a new entry to the end of a list, use <APPEND> as the index for the new entry. Use the
<APPEND> keyword with the Update Page action in a data transform, and in an activity step.
Important: When iterating over a list in a data transform by using the For Each Page In action, you
cannot use the <APPEND> keyword. Instead, add a step to the iteration and use the Append to or
Append and Map to actions. For more information on using these actions in a data transform, see the
Help topics Data Transform form — Completing the Definition tab — Append to action and Data
Transform form — Completing the Definition tab — Append and Map to action.

259
©2018 Pegasystems
To write a new entry to the beginning of the a list, use <PREPEND>.
To identify the last item in a list, use <LAST>.
If you want to enter an item sequentially in a list, and you do not know the index number, use the
<CURRENT> and <INSERT> keywords when iterating over the entries in a list. For example, for a
purchase order application that allows users to order items, there is a list of unique vendors. For each
line item ordered, business users select a vendor from a list of preferred vendors for the purchase.
Follow these steps to create a list of unique vendors.
1. Create a data transform to iterate over the list of order items.
2. Identify the vendor for the item.
3. Compare the vendor to the list of unique vendors.
If the vendor is not listed, copy the vendor from the order item to the list of unique vendors. Within the
iteration, use the <CURRENT> keyword as the index for the order item.
Tip: Pega also provides a standard activity parameter, pyForEachCount, for identifying the current entry
in a list. Unlike <CURRENT>, pyForEachCount can be passed as an activity parameter and used in
expressions.
To configure a data transform step to iterate over a list, starting with the first entry, select the For Each
Page In action. The following example shows a data transform configured to iterate over a list of order
items in a purchase request that creates a list of unique vendors.

Navigate nested embedded pages

When navigating a hierarchy of embedded pages, you may need to refer to a parent page in the
hierarchy. Pega provides two keywords for accessing the correct page in a hierarchy of embedded
pages.
Top – Refers the top most page of the embedded page
Parent – Refers to the parent page of the embedded page
Note: If the embedded page has only one parent and no grandparents in the hierarchy, Top and
Parent refer to the same parent page.

260
©2018 Pegasystems
How to execute SQL using Connect SQL rules
When you need to execute a SQL command or stored procedure as part of a database operation, you
may use a Connect SQL rule to interact with an external database. Connect SQL rules can be invoked
from a data page or from an activity using RDB methods. The Application Explorer lists the Connect
SQL rules in your application. The Records Explorer lists all Connect SQL rules that are available to you.
For information about creating records, see Connect SQL rules Completing the Create, Save As or
Specialization form.

Keywords and notations

Keywords and notations describe mapping to the external database. These keywords and notations
provide a two-way mapping between Pega features — the clipboard, Database Name instances, and
Database Table instances — and the tables, rows, and columns of the external database. Employ the
syntax described in Connect SQL form Data mapping to cause Pega to make run-time substitutions to
the SQL before sending it to the external database.
The Connect SQL rule provides four tabs for supported operations Open, Delete, Save, Browse. In
addition, the History tab provides information about the rule history. Use these tabs to enter SQL
statements to execute when performing the operation.
A dynamically created WHERE clause can add flexibility to SQL connections. See the ASIS keyword to
build a dynamic WHERE clause in Connect SQL rules.

Use a Connect SQL rule to map to a table

The following example includes a Connect SQL rule used to access an external POSTALCODES table. In
the example, the query requests a city and region for a postal code. To map the columns in the select
to properties in the clipboard page, use the keyword “as” for the select.
The Applies To class is ADV-Purchasing-Int-PostalCode. The mapping between columns and properties
takes place within the Connect SQL rule. The mapping does not need to be defined in the class rule.
The Package Name indicates the SQL language variant used. The Request Type field holds the name of
the rule.

261
©2018 Pegasystems
Note: A best practice is not to hardcode table names in the SQL statement. As an alternative, use the
class keyword that uses the Database Table instance configured for the class to determine the table
name.
The where clause references the ID property in the step page.
Use the characters /* and */ to surround comments within the SQL statement.
To include SQL debugging and return status information from the database software, enter a line at
the top of the SQL code defining the name of the page on which to record the messages.

262
©2018 Pegasystems
In this statement, the query searches for a city. The Asis keyword prevents the system from placing
spaces or quotes around the value. Using wildcard characters is possible because the Asis keyword is
included in the syntax.
KNOWLEDGE CHECK

Describe one way to add flexibility to SQL connections.

A dynamically created WHERE clause can add flexibility to SQL connections.

263
©2018 Pegasystems
Connecting to an external database
Use the Database Table Class Mapping landing pages to map database tables to an external class in
Pega. The wizard guides you through the steps to create the records needed to map a database table
to an external class in your application.
Pega builds upon commercial relational database products from Oracle, IBM, and Microsoft. Detailed
knowledge about the database is not needed for most application tasks. Senior system architects and
system architects can create new rules and new properties, and save data without updating the
database structure and without the need for a database administrator.

Register an external database

Each relational database you need to connect to must be defined as a database instance. When the
Database instance has been created and a suitable JDBC library has been installed on the server, you
can connect to and interact with that database.

Test connectivity
A database table instance maps classes and class groups to relational database tables or views in a
database. Before creating a Database Table instance, you must confirm that the table or view is
present in the database schema.
You do not need to create a Database Table instance for every concrete class. At run time, the system
uses pattern inheritance and class groups to locate the appropriate Database Table instance for an
object. If none is found, the system uses the table pr_other as default.
However, each class representing a table in an external table must have a Database Table instance.

Specify the database table

1. From the Designer Studio menu, select Data Model > Classes and Properties > Database Class
Mapping to open the Database Class Mappings landing page.

2. In the upper-right corner of the landing page, click New External Database Table Class Mapping

264
©2018 Pegasystems
 to save an existing one or create a new database table instance .

Map database table columns to properties in the ruleset

class
1. In the Database Table Class Mappings dialog, select a database name and table name:
a. For Database Name, select the database instance that holds the table to which you are
connecting.
b. For Schema Name, select the database schema to which you are mapping.
c. For Table Name, select the table you will use to generate the class, properties, and database
table instance in your application.
2. Specify the ruleset and version for generated rules
a. For Ruleset Name, select an existing Ruleset that will contain the generated rules for the table
mapping.
b. Enter the Ruleset Version for the generated rules.
c. Enter the Class Name of the class to create and map to the external table.

265
©2018 Pegasystems
Now that you have selected rulesets and versions for the table mapping, and created a class to map to
the external table, the information is saved in the External Mappings tab of the class rule.

Map the database columns to properties in the ruleset

class
1. Select the Key column check box to indicate that the associated properties will be designated as
keys for the generated class. Columns that are keys to the table will also be keys to the generated
class.
Note: The Key cannot be edited once the external table has been mapped.
2. Select the Column Name for the name of a column in the external table.
3. The Data Type is the database-specific data type that was defined when the column was added to
the table.
4. In the Property Name column, enter a name for the new property. The Property Name is the name
of the property in the external class that represents the table column in the Column Name Field.
Leave the field blank to use the column name from the database as the property name.
5. In Property Type, enter the type of property that will be created. This is dependent on the data
type.
6. In the Map All/None column, select the:
a. Check box to map the property to the specified class
b. Map All/None check box to select or deselect all the columns specified class
To learn about the purpose of each of the tables in the PegaRules database, refer to Database tables in
the PegaRules database.

266
©2018 Pegasystems
 Simulating integration data
Introduction to simulating integration data
Pega provides the ability to simulate integrations with services for testing purposes or when the data
source is unavailable. You simulate an integration to unit test the integration connector.
After this lesson, you should be able to:
l Explain the need for simulated data in testing integrations
l Explain how to simulate a connection to an external system
l Create an integration simulation

267
©2018 Pegasystems
Integration simulation
Integration simulation is useful in situations where the external service is not available or when you
want to dictate the response returned. You can simulate any external service as long as you know what
data the external service is expecting and returning. The exact interface definition does not need to be
in place.
For example, an external service might not be implemented yet. Simulating the service allows you to
implement case processing before the service is available.

Simulation is also useful in testing since it allows you to dictate the response returned. For example,
when testing all permutations of a flow.

KNOWLEDGE CHECK

When would you simulate an integration?

268
©2018 Pegasystems
You would simulate an integration when the service is not available or when the response needs to
be dictated.

269
©2018 Pegasystems
How to simulate an integration
Pega uses connectors to integrate with external systems. A connector can be invoked from either a
data page or an integrator activity. Data pages are used to read, or pull, data from an external system.
Activities are used to write, or push, data to an external system.
If the interface definition is available, a connector can be generated using one of the connector
wizards. How an integration is simulated depends on whether or not a connector is available.
If you need to simulate an external service which has not yet been defined, but you know what data the
service is going to return, then simulate the data page source or integrator activity. Simulate the
connector if it already exists.

Simulating a data page

In the data page, select the Simulate data source option to simulate the data source in the data page.
You can simulate a data page using a data transform, report definition, or activity. Selecting simulation
disables any data source configured.

Select Designer Studio > Data Model > View external data entities to open the External Data
Entities landing page and get an overview of simulated data pages in your application. Source systems
marked with a green dot are production ready. Source systems marked with an orange triangle are
simulated.

270
©2018 Pegasystems
Simulating an integrator activity
If you are invoking the connector from an integrator activity, a simulation data transform can be
applied to populate the case with response data.
Use a data transform to define simulation data if your connector is invoked from an integrator activity.
Set the simulation data directly in the case in the same way you would map the response data
returned from the connector.

Configure connector simulation

You can simulate a connector when the interface of the service to which you are integrating is defined
and the connector exists, but the service may still be under development or not yet deployed.
The Connectors landing page (Designer Studio > Integration > Connectors > Connector
Definitions & Simulations) provides you with an overview of available connectors and their
simulations. No connector simulations are available out-of-the-box.
Note: Simulation is not available for SQL connectors.

271
©2018 Pegasystems
Connectors are simulated using a simulation activity. The simulation activity sets the properties to be
returned by the external service on the integration page used by the connector.
A connector can be simulated either for all users in the application using the Global option, or for the
current user only using the User session option.
Follow these steps to enable simulation of a connector.
1. Navigate to the connector you want to simulate.
2. Specify the simulation activity.
3. Select the scope: Global or user session.
4. Apply the changes to activate the simulation.
KNOWLEDGE CHECK

When would you use the simulation option in a data page?

When the connector has not yet been generated

272
©2018 Pegasystems
Simulating connector data
Connector simulators can be set up for most connector types. First create the simulation activity for the
connector. Then configure the activity for the connector.

Create a simulation activity

1. Create a data transform in the same class as the connector.
2. Use the values on the request page to create responses based on incoming values.
3. Set values on the response page to simulate the response returned by the external service.

4. Create the simulation activity in the same class as the connector it simulates.
5. Apply the data transform in the simulation activity.

Configure simulation for a connector

1. Open the simulations settings for the connector. You have two options:
a. At the bottom of the connector record, click Simulations.
b. On the Connectors landing page (Designer Studio > Integration > Connectors > Connector
Definitions & Simulations), click the Simulations link for the connector.
2. Specify the simulation activity.

273
©2018 Pegasystems
3. Select the simulation scope.
4. Click Submit.

274
©2018 Pegasystems
 Addressing integration errors in
connectors
Introduction to addressing integration errors
in connectors
Connectors are used to integrate with external systems. Errors may occur when a connector invokes a
service. Errors might be related to the infrastructure — for example, the connector may not be able to
connect to the server. Errors may also be due to the configuration — for example, a service might
return a response that the connector does not understand.
There are different mechanisms for handling errors, depending on how the connector is invoked. This
lesson demonstrates how to build reusable error detection mechanisms for connectors.
After this lesson, you should be able to:
l Describe the role of error detection when configuring connectors
l Configure error detection for an integration
l Address errors returned by a connector

275
©2018 Pegasystems
Error handling in connectors
Connectors are used to read data from or write data to an external system. Two types of errors can
occur when integrating with an external system:
l Transient errors typically do not last long; they correct themselves over time. For example, the
connector is unable to connect because the application is being restarted and is temporarily
unavailable.
l Permanent errors are typically due to a configuration error or an error in the remote application
logic. For example, an invalid SOAP request is sent to a SOAP service. In this scenario, the error
persists until the SOAP request message is fixed.

Since connectors communicate with external systems, the possibility of something going wrong always
exists. Therefore, a best practice is to include error handling for all connectors.
For transient errors, post a note to alert the end user that the integration failed. Ask the user to retry at
a later time. Alternatively, if the response is not immediately needed, the connection can be
automatically retried.
For permanent errors, write the details to a log file so that errors can be investigated and fixed. In
addition, you might want to implement a process for the investigation and fixing.
KNOWLEDGE CHECK

What type of errors typically correct themselves over time?

Transient

276
©2018 Pegasystems
How to configure error detection
The way errors are detected depends on how the connector is invoked. Connectors can be invoked by
data pages or activities. When data pages and activities invoke a connector, the best practices are to:
l Add error detection to all data pages and activities
l Invoke a reusable data transform to handle errors
Pega provides a template data transform called pxErrorHandlingTemplate. This can be used to create a
reusable error handling data transform. The error handler data transform can be used with both data
pages and activities. The pxErrorHandlingTemplate data transform is in the base class and is shipped as
part of the product.
In addition, each connector has an error handling flow. Pega automatically invokes the error handler
flow if the error is not detected by another mechanism.

Data pages
Connectors are used with data pages to read data — such as customer and insurance policy data —
from an external system. Data pages are loaded on demand. All data source errors must be handled as
part of the data page load mechanism. The type of data source being leveraged to load the data page
affects how errors are detected and handled.
l Connectors, report definitions, and lookups use the response data transform to detect errors.
l Activities use a transition condition in the activity step to detect errors.
The response data transform is invoked after the connector call is complete. If there is an issue,
messages are added.

In your response data transform, use a when condition to check for any error messages on the page. If
an error has occurred, apply the reusable error handling data transform.

Activities
Connectors are used with activities to write data to external systems. For example, a connector may be
used to update data in a system of record. When the connector is invoked from an activity, use a
transition condition to check for the presence of an error in the activity step invoking the connector. If
an error is detected, apply the reusable error handling data transform.

Error handling flow

The error handling flow feature detects errors that are not detected in a data page or an activity. This
feature is always enabled.

277
©2018 Pegasystems
The error handler flow allows you to implement a process for handling the error. It is typically used
when the connector response is not required immediately — for example, when updating a legacy
system.
<<image: error handler flow>>
KNOWLEDGE CHECK

In data pages, a best practice is to detect errors in the __________.

response data transform

278
©2018 Pegasystems
Configuring error detection for integration
The following procedure explains how to configure error detection and handling for data pages and
activities. Data pages and activities invoke connectors to read data from and write data to external
systems.

Configure error detection for a data page

To configure error detection for a data page, create a new data transform for error handling. This data
transform is applied when an error is detected.
1. In Designer Studio, search for the standard data transform called pxErrorHandlingTemplate.

2. Save pxErrorHandlingTemplate with a new name to create a new data transform in your application.

Next, in your response data transform, apply the error handling data transform you just created.

279
©2018 Pegasystems
1. Open the response data transform. Create a new response data transform if one does not exist.

2. Use the standard when condition pxDataPageHasErrors to detect errors in the data page.
Important: The steps highlighted in the following image are automatically added to response data
transforms by default. When you change the name of the error handling data transform, you must
update step 2.2 to apply your error handling data transform instead of the standard error handling
data transform.

Configure error detection in an activity

The error handling data transform may be used when connectors are called from an activity as well.
1. Define an error label for the error handling step.
2. Identify the steps in your activity that include error detection. Click Jump to define a transition
condition.

3. Select the StepStatusFail when condition to detect errors. Jump to the error step when an error

280
©2018 Pegasystems
 occurs.

4. You can use the error handling data transform you created previously that specifies how to handle
the error. Select the Apply-DataTransform method. In the error handling step, select your data
transform.

281
©2018 Pegasystems
How to address errors returned by a
connector
(missing or bad snippet)
The following process describes how to address errors returned by a connector. Options to address
integration errors depend on how the connector is used. Use an error handling data transform if the
errors are detected using a:
l Response data transform in a data page
l Transition condition in an activity
If the error is not detected in the data page or the activity, then the error handler flow for the
connector is invoked to detect the error.

Error handling data transform

If there is an immediate need for the response to be returned by the invoked service, you should:
l Display an error message
l Write the error to the log file
Writing a message to the log file helps troubleshoot errors. For example, a log file can be analyzed to
identify patterns related to a specific error. In the log message, include details about the connector
request to help identify the cause of the error.
Another option is to generate an email that includes error details. The template error handling data
transform includes examples of standard utility functions to:
l Get available messages
l Clear messages
l Add a message to the data page
l Write a message in a log file
l Send an email

282
©2018 Pegasystems
Retry a connector invoked from a data page
If the returned error is temporary, you may give the user the option to retry the connector. To retry the
connector, configure the data page refresh strategy:
l Create a when condition that returns true when there are no error messages.
l Set the Do not reload when setting so the data page does not reload if there are no error
messages.

Error handler flow

When the response to be returned by the connector is not immediate needed for further processing,
consider using an error handler flow. Configure the error handler flow in the service tab for the

283
©2018 Pegasystems
connector. The error handler flow feature is always enabled. The error handler flow is not executed if
the error is detected in the response data transform or in a transition in an activity.
By default, connectors use the standard ConnectionProblem flow. The flow can be copied and
customized. You may also choose to create an alternative error handler flow.

When an error occurs, the original flow execution is paused. Control is handed over to the error
handler flow. If the resource is unavailable, a transient error may be preventing processing. If there is
no transient error, the connector is retried, and processing continues in a flow called FlowProblems.

The FlowProblems flow either routes the work item to a problem flow workbasket or notifies an operator
about the issue. The operator may:

284
©2018 Pegasystems
l Retry the connector
l Resume the flow without retrying the connector
l Restart the initial flow
l Cancel the error handling flow
KNOWLEDGE CHECK

When would you use an error handler flow for your connector?
You would use it when the response is not immediately needed and a process for handling the error
is required.

285
©2018 Pegasystems
 Managing integration settings
Introduction to managing integration
settings
The use of global resources settings for references to external systems, rather than fixed text values in
rule forms, allows greater flexibility for changing values such as port numbers, addresses, and URLs.
In this lesson, you learn how to apply global resource settings to reference any property of the
appropriate type on a data page. You also learn how to apply global resources settings in rule forms.
After this lesson, you should be able to:
l Explain the need for global resource settings
l Compare mechanisms for setting global resource settings values
l Describe the global resource settings pattern
l Add resource settings for an integration

286
©2018 Pegasystems
Global resource settings
Before an application is live, it moves through many environments. Typically, applications go through
development, staging, QA, and production. When migrating an application from one server or
environment to another, references to the external systems connected to the application (such as
endpoint URLs and JNDI servers) typically change. The information required to connect to these
external systems must be modified, depending on your environment.

In this example, you have a web service connector that accesses a web service. There is also
configuration for the email server used to send and receive email in the application. When the
application moves from the staging environment to the production environment, the URLs and host
names all have to change because the production web service and email server have different values.
The example provides only two sets of settings, but an application could have dozens of connectors
and setting information. You do not want to have to remember all of the different resources and
update each one individually. Additionally, some of the values are in rules — these belong to locked
rulesets. You do not want to unlock your ruleset after promotion. The risk is that you would miss one or
two settings and delay the application going live.
To avoid missing a setting, use the Global Resource Settings pattern to reference the external
systems. Global Resource Settings allow you to define values for settings that can vary depending on
environment, without requiring the update of integration rules and data instances.

287
©2018 Pegasystems
In this pattern, you create a class that contains the configuration settings for an integration that has
values able to change from one environment to the next. You then have your resources access a data
page to load those settings. This allows you to have a place to maintain and update these settings.
KNOWLEDGE CHECK

What is the largest benefit of using global resource settings?

The largest benefit is the ability to reference external systems in a way that can vary depending on
environment, without requiring the update of integration rules and data instances.

288
©2018 Pegasystems
How to configure a global resource setting
for a connector endpoint
When you configure a global resource setting (GRS) for an integration, you first create a class for the
references. You place all GRS rules in the same ruleset as the integration rules. Next, you determine
which environment references to external systems will use the feature. Then, you create a page
property for each environment reference. Continue the process by creating a data transform to assign
values to the environment properties using utility functions. Finally, you create a data page to tie these
artifacts together.
Assume that you have generated a connector for an inventory check SOAP service using the Create
SOAP Integration wizard.

Designate a class for the references

The first step in implementing GRS is to create or identify a class to contain environment properties
that represent those references.
As a best practice, create the class in the integration's base class. This helps avoid later confusion
when users access multiple integrations, since each integration has its own data page. Create a class
called Env in the base integration class.
In this case, create the Env class in the Inventory class generated by the Create SOAP Integration
wizard.

Create the environment properties

The next step in implementing the GRS is to determine which environment references to external
systems will use the feature. This table contains classes that support the GRS syntax. Create a page
property for each environment reference. For SOAP connectors, use the class Embed-Env-SOAP.

289
©2018 Pegasystems
Create a data transform to assign values to the
environment properties
After you create the environment properties for the integration, you must create a data transform to
assign values to those properties. This data transform is used to source a data page.
Note: Hard coding the environmental variables in the data transform requires you to unlock the
ruleset to update the values. As a best practice, never unlock a locked ruleset.
Pega 7 provides several ways of specifying environmental variables without requiring unlocking
rulesets. The following table provides the options with relevant utility functions used to obtain the
value.

Type Function Description

Dynamic getDataSystemSetting This function reads the specified Dynamic System Settings
System from the database and returns it as a string.
Settings
Java System getJavaSystemProperty This function returns the specified Java system property
Property as a String.
Java getJavaPropertyFromFile This function loads the specified Java properties file and
Properties File returns the value of the property specified in the
function's Key parameter as a String. If the property
cannot be found, the function returns an empty string.
JNDI Entry getJNDIEntry This function does a lookup for the specified JNDI entry
and returns it as a string. If the lookup cannot be
performed, the function returns an empty string and
writes an error to the log.

Note: The environmental variables should not be packaged as part of the application since that would
overwrite the settings on the target system when an application is migrated.
In this example, a Dynamic System Settings is used to store the values. Since Dynamic System Settings
are data, they can be updated without the need of unlocking a ruleset.
Consider a naming convention to categorize the Dynamic System Settings entries and assure their
uniqueness. For example, the first entry could be GRS, a namespace for these types of entries. The
second is the name of the interface, and the third is the name of the property.

290
©2018 Pegasystems
In this example, the getDataSystemSetting utility function rule is used to obtain the value in the data
transform.

Note: You must Base64 encode any passwords before you use them in rules or data instances. Use the
Encode() function to encode passwords.

Create a data page

The final rule you create is a data page that ties everything together. As a best practice, choose a name
that includes the name of the integration. This helps avoid later confusion when users access multiple
integrations (and each integration has its own data page).
For object type, enter the class created in the first step and select the node scope. Use the data
transform created to populate the data page.

291
©2018 Pegasystems
Use the Global Resource Settings syntax for references to
external systems
After you have set up the data page for GRS, use the following syntax to refer to the values:
=DataPageName.IntegrationPropertyName.FieldPropertyName
Where:
l PageName is the name of the data page, and
l PropertyName is one of the properties
This is how the reference looks if you want to refer to a SOAP Service Endpoint URL, your data page is
named D_InventoryEnv, and the property is named InventoryCheck. The setting is on the SOAP
connector's Service tab.

Execution-time sequence
The following list shows the execution-time sequence for determining the Endpoint URL for the SOAP
connector:
1. The SOAP Connector is invoked.
2. A data page property is referenced.
3. The data transform for the data page is executed if the page is not already available on the
clipboard.
4. The data transform invokes a utility function to obtain the value of, for example, a dynamic system
setting.
5. The value is used by the SOAP connector to invoke the service.

292
©2018 Pegasystems
APPLICATION DEBUGGING

293
©2018 Pegasystems
 Reviewing log files
Introduction to reviewing log files
Pega generates log files to track application and system activity. In this lesson, you learn how to use the
PegaRULES Log Analyzer (PLA) to read and interpret log files.
After this lesson, you should be able to:
l Describe the importance of Pega log files
l Identify when to review log files to aid application development
l Describe the purpose of the stack trace file
l Analyze system logs using the PegaRULES Log Analyzer (PLA)
l Access system logs in Pega
l Set up remote logging

294
©2018 Pegasystems
Log files
Pega writes errors, warnings, and other debug information to log files. Logs track exceptions and other
events that impact your application, and provide valuable insight into their cause. Each log is managed
by an appender, which determines the type of events written to the log file. Pega manages logs based
on the appender configuration in the prlogging.xml file for the node.
In Designer Studio, logs are available from the System Operation landing page. Depending on your
settings, you may see the following log files:
The PEGA log contains warnings, errors, and information messages about internal operations. This file,
also referred to as the Console log or System log, is used for debugging the application. By default, the
Pega log is filtered to entries that match the current operator ID.
The ALERT log contains performance-related alerts. Use the PLA tool to parse and summarize this file
into a Microsoft Excel spreadsheet. See Understanding Alerts.
The ALERTSECURITY log contains alerts (identified by the prefix SECU) that suggest improper
configuration of Internet Application Composer facilities, or overt attempts to bypass system security
features through URL tampering. See Performance alerts, security alerts, and AES.
The BIX log is created by the Business Intelligence Exchange during extract operations. BIX is an
optional add-on product that provides the extract functions of an ETL (extract, transform, and load)
utility.
The SERVICES-PAL log contains performance data saved from services. See Performance tool —
Statistics for services in the SERVICES-PAL log.

Filter criteria
When you view a log file, Pega displays only lines of the log for your own Operator ID (for all your
sessions on this node), in pages of 25 lines each. You may view or set log filtering criteria. To view other
entries, you have the option to change or remove the filter.

Logging level settings

Use the Logging Level Settings tool to control which logging events appear in the Pega log. The
prlogging.xml configuration file defines the levels of logging events. In a multinode Pega system, you
can create separate prlogging.xml files for each node.
Note: Rulesets and the Pega class hierarchy are not relevant to logging. If you set logging events for an
activity named Data-Party.Research and your system includes several activities of that name (in
various RuleSets and versions), executions on the current node of any of these activities may produce
logged events.
You may temporarily override the severity settings in the prlogging.xml file for the current node. When
you make this temporary change, the prlogging.xml file is not altered. Logging on nodes other than
your current node is unaffected.
For example, you can change the logging level for activities in the Work- class from FATAL to DEBUG.
Thereafter, olog() calls in Java steps that have a severity setting of DEBUG or lower appear in the Pega
log.

295
©2018 Pegasystems
The changes you make take effect immediately and remain in force until the server on the node is
stopped, or until you or another developer uses the Logging Level Settings tool again to reset the
logging level.
For more information about how to change the diagnostic logging level in a Pega application see
Logging Level Settings tool.
KNOWLEDGE CHECK

What is the purpose of an appender?

An appender manages the writing of errors, warnings, and other debug information to a log file.

296
©2018 Pegasystems
How to access system log files in Pega
System administrators monitor logs throughout the development process. Using the logs to debug your
Pega application as you work results in fewer errors during testing and speeds time to delivery.
In Designer Studio, logs are available from the System Operations landing page. Log files can also be
obtained from the System Management Application (SMA).
The Pega log file is used for debugging. The other logs in the list illustrated in the following image
apply to performance.

You can view logs in Designer Studio or download the current log from the server to your workstation.
To view a log, click the text link or zip link to download the log. You can import the file into Microsoft
Excel, using a single asterisk character (*) as the field separator character, for ease in reading, sorting,
or searching.
Application server authentication may be required to read PEGA log files. Access is controlled by the
PegaDiagnosticUser role in the web.xml file for the DiagnosticData servlet. Consult your Pega 7
Installation Guide for instructions.

297
©2018 Pegasystems
Log messages
In an activity, use the Log-Message method to add a message to the Pega log. For more information,
refer to the Log-Message method help topic.

298
©2018 Pegasystems
How to use the PegaRULES Log Analyzer (PLA)
Regular monitoring of log files during development and production helps ensure your application is
operating properly. The PegaRULES Log Analyzer (PLA) is a standalone web application that
developers and system administrators can use to view summaries of console logs.
Use the PLA to test new or reconfigured Pega applications during user acceptance testing (UAT),
performance and stress testing, and immediately after deployment into a production environment.
Testing reconfigured applications during UAT, during performance testing, and right after deployment
is important because performance, stability, and scaling issues are most likely to occur during these
times.
The PLA consolidates and summarizes three types of logs — Alert, Pega, and Garbage Collection (GC) —
from individual Pega JVM server nodes in your application system. The log data provides key
information about operational and system health.
View log information to quickly identify, diagnose, and remediate issues that may be degrading or
compromising your application:
l To monitor performance, review the Alert log. The Alert log contains diagnostic messages that
identify individual system events that exceed performance thresholds or failures. Alert messages
contain a set of field values that identify the alert, the conditions that caused it, and the state of
system when it occurred. The Alert log supports performance-related monitoring.
l To monitor system stability, review the Pega log. The Pega log gathers system errors, exceptions
(with their stack trace statements), debug statements, and any other messages not specified as
alerts. The Pega log can contain messages created by your activities as well as messages created by
standard rules. The Pega log is also referred to as the console log or system log.
l For insight into how your Pega application is using memory, monitor the JVM garbage collection
log.
Each node on a Pega system produces two log files, the Alert Log and the Pega log. The Pega log
contains messages created since the most recent start of the server. The log file is usually named
PegaRULES-YYYY-MMM-DD.log. The date portion of the name indicates the date the application server
was recently started (on the current node).
KNOWLEDGE CHECK

Name two specific times in the project life cycle when reviewing log files is important.
During UAT performance and stress testing
Immediately after application deployment

For more information about the PLA, refer to:

Understanding the PegaRules Log Analyzer
How to User the PLA
For more information about alerts, refer to:
Understanding Alerts
Working with the My Alerts display

299
©2018 Pegasystems
Performance Alerts, Security Alerts and AES
For information about how to customize logs, refer to:
How to customize logs with the prlogging.xml file

300
©2018 Pegasystems
Monitoring logs remotely
Use the System Management Application (SMA) to perform remote logging. Remote logging establishes
a connection between the server and a standalone Pega application running on a desktop. The remote
logger is updated near real time.
Note: The logs are updated in near real time. If you execute the steps too quickly, the remote logger
will be unable to keep up.
1. Select System > Operations > SMA to open the SMA.
2. Select a Node. The SMA displays PegaRULES Node Information. Each server hosting the Pega rules
engine software (but sharing one system name) is known as a node.

3. Expand Logging and Tracing to run the remote logger, and select Remote Logging.

301
©2018 Pegasystems
4. Click the link at the bottom of the Remote Logging dialog to download the log4j socket server.

5. Extract and run the log4j socket server. The remote logger user interface opens.

6. Now that the log4j server is running, establish a connection by returning to the SMA and specifying:
l The host
l The port displayed in the first line of the logger (default is 8887)
l Any filters that are appropriate
You are now ready to monitor logs files in near real time as you step through a process to identify
when exceptions or events occur.
For additional information, see How to install and use remote logging.

302
©2018 Pegasystems
 Analyzing application performance
Introduction to analyzing application
performance 
Pega provides tools to evaluate application performance. Performance statistics help you distinguish
between performance issues that arise in the Pega 7 server, the PegaRULES database, or external
systems called by the workflow. In this lesson, you learn how to use the Performance Analyzer,
Performance Profiler and Database Trace to evaluate performance.
After this lesson, you should be able to:
l Describe the importance of performance testing
l Describe the purpose of the Performance Analyzer (PAL)
l Describe the purpose of the Database Trace
l Describe the purpose of the Performance Profiler

303
©2018 Pegasystems
Performance testing
Performance is an important aspect of any system. User satisfaction and business value are often
measured by the perceived quickness of the system. Pega provides a full suite of tools to monitor and
address performance. You use these tools during development to ensure that your configuration
performs optimally.
The Performance landing page provides access to the three performance tools: Performance Analyzer 
(PAL), Database Trace, and Performance Profiler. These tools are also available by clicking Performance
tool in the toolbar, and they are described in detail in the Help topic, About the Performance tool. Use
the performance tools to collect performance statistics. Performance statistics can help you distinguish
between performance issues that arise in the Pega 7 Platform server, the database, or external systems
called. In all cases, the statistics can help you determine how to improve performance.

Performance Analyzer (PAL)

The Pega 7 Platform always accumulates cumulative resource statistics. Use the Performance Analyzer
(PAL) to understand the system resources consumed by processing a single requestor session. PAL
works on existing data, and this means that it does not degrade processing.

Database Trace
The Database Trace tool is useful in tuning the application in case of any database performance
issues. Run Database Trace if PAL readings indicate performance issues in the database operations.
Database Trace can trace all the SQL operations like queries or commits that are performed.

Performance Profiler
Use the Profiler to obtain a detailed trace of performance information about the execution of activities,
when condition rules, and data transforms executed by your requestor session. The Profiler traces
every execution (in all Threads) of rules of these three types in all rulesets. The Performance Profiler
should be run in conjunction with Performance Analyzer to narrow down the specific step
(Performance Profiler) of the cause (Performance Analyzer).
For more information about the System Performance landing page, see the Help topic System
Performance Landing page.
KNOWLEDGE CHECK

Which performance tool is used to display resource statistics recorded by Pega Platform?
Performance Analyzer (PAL)

304
©2018 Pegasystems
How to analyze performance with the
Performance Analyzer
The Performance Analyzer (PAL) provides a view to all the performance statistics that Pega Platform
captures. You can use PAL to understand the system resources consumed by processing a single
requestor session.
PAL is available on the Performance landing page (Designer Studio > System > Performance) or from
the Performance tool in the toolbar.

Measuring performance
The first step to measuring your application performance is to take measurements. You start by
clicking Reset Data to clear any data in the tool. Since the system is constantly monitoring
performance, you are eliminating any previously recorded entries from your results by resetting data.
You have two options for adding a reading: Add Reading and Add Reading with Clipboard Size. The
only difference between the two readings is the addition of the clipboard size, which takes extra time
to calculate.
When adding a reading, the best practice is to define points that identify what occurred during that
reading. For example, use one reading per flow action or screen render, depending on what process
you are measuring.
Click Save Data to download the results to an Excel file.

Analyze performance data

The INIT row shows the totals when this Performance display first appeared. Each reading added is
shown as a DELTA — this indicates the change from a previous reading. The FULL reading is the total
sum of all the statistics from the last time the data was reset.

In the readings displayed, you can see the top delta has a reading that shows 1.61 for RA Elapsed. All
values are in seconds. RA Elapsed represents the time spent in rule assembly. These results can skew
performance readings as rule assembly, also known as first use assembly or FUA, is expensive but only
occurs once. This is evidenced by the results you see here. The total elapsed time was 2.82s, and 1.61s
of that time was spent in rule assembly. If you did not have the additional 1.61s, the total time would
be less than half the measured number. FUA also affects the other readings such as the total rules
executed, the reads from the database, and various I/O counts.

305
©2018 Pegasystems
To obtain results not affected by FUA, you should run through the process once to ensure all rules have
been assembled before taking any measurements. That was not done here in order to demonstrate the
impact this has on performance readings.
Clicking INIT, DELTA, or FULL displays more details about the reading. Many different results are
available to you for analyzing the performance.

Results have no magic number. A result of 10 minutes may be acceptable in one situation, anything
over 100 milliseconds is considered too slow in another. You must work with the lead system architect
and the business to determine an acceptable result for each step of the process.

306
©2018 Pegasystems
How to analyze application performance with
Database Trace
The Database Trace produces a text file containing the SQL statements, rule cache hit statistics,
timings, and other data that reflect your requestor session's interactions with the Pega 7 Platform
database or other relational databases. Familiarity with SQL is not required to interpret the output.
The Database Trace is available on the Performance landing page (Designer Studio > System >
Performance > Database Trace) or from the Performance tool in the toolbar.

Configuring the Trace settings

Click Trace Options to open the settings window. The settings window lists all possible events to trace.
If an event does not apply to a situation, it should be removed from the list to streamline the results.
You also have the option to generate a stack trace. Generating the stack trace is an expensive process
and should only be used when required.

Taking readings
Click the green Play button to start Database Trace. Click the red Stop button after you have
performed the steps you want to trace. After stopping the tool, the table is updated with the results for
all the threads it traced.
You need to identify the thread corresponding to the process where you performed your work. When in
doubt, look for the largest size — it is most likely the one in which you performed your work.

307
©2018 Pegasystems
Click the Download icon to save the results in a tab delimited file format so they can be opened using
any spreadsheet program, such as Excel, to review the Database Trace readings. The following image
shows an example of the file to review.

308
©2018 Pegasystems
How to analyze application performance with
Performance Profiler
The Performance Profiler is useful when determining which part of the process might be having
performance issues, or identifying the particular step of a data transform or activity that might have a
performance issue.
When you use the Performance Profiler, you first record readings of the application's performance.
Then you analyze the readings to identify problems.
The Performance Profiler is available on the Performance landing page (Designer Studio > System >
Performance > Performance Profiler) or from the Performance tool in the toolbar.
Once you locate the Performance Profiler, click the green Play button to start recording the steps you
want to trace in your application. Click the red Stop button after you have performed the steps. After
stopping the tool, the table is updated with the results for all the threads it traced.
Note: The Performance Profiler requires substantial processing overhead. Disable the Performance
Profiler as soon as your data collection is complete.
When you review the trace log, you need to identify the thread corresponding to the process where you
performed your work. When in doubt, look for the largest size. The largest thread is most likely the one
were you performed your work.

Click the Download icon to save the results in a comma-separated-value file format. The results can
then be opened using any spreadsheet program, such as Excel, to then review the Performance Profiler
readings.

309
©2018 Pegasystems
To learn more about the Performance Profiler landing page, see the Help topic About the Performance
Profiler land page tab.

310
©2018 Pegasystems
APPLICATION ADMINISTRATION

311
©2018 Pegasystems
 Securing an application
Introduction to securing an application
Privileges assigned in an access group restrict access to application functionality.
In this lesson, you learn how to authorize users to define roles and assign privileges to members of an
access group.
After this lesson, you should be able to:
l Explain how user roles relate to access groups
l Explain how privileges authorize users to perform specific tasks
l Create access groups and users
l Explain the role of the Access Manager in securing an application
l Configure access control with Access Manager
l Secure a workbasket
l Secure an attachment
l Secure a specific rule
l Require a privilege to perform a flow action

312
©2018 Pegasystems
Access control
Each user of an application has a defined role in processing cases. Some users can only create cases,
while other users may be responsible for reviewing cases and determining case outcomes. Ensuring
that the correct user performs a task or action is access control.
Access control depends on two factors: authentication and authorization. Authentication confirms
the identity of a user and verifies that the user is allowed access to an application. Authorization
determines what data the user can view and what actions the user can perform.
KNOWLEDGE CHECK

___________________ verifies a user's identity and access to an application.

Authentication

KNOWLEDGE CHECK

___________________ determines the actions the user can perform in the application.
Authorization

In Pega, the records for the operator ID, access group, and application allow authentication of a user.
For example, an access group named PurchaseRequest:Managers indicates that a user is a manager for a
purchase request application. An access group named TimeTracker:Users indicates that a user is a case
worker for a time-tracking application.
A user can belong to multiple access groups, but only one access group is active at a single time. When
a user signs in, Pega identifies the default access group and opens the corresponding application in
the specified portal.

Note: When users switch between applications, Pega changes the active access group and resets the
user session. This automatically closes any open forms and discards unsaved work.

313
©2018 Pegasystems
Authorization consists of identifying the types of users who access the application and determining the
actions those users can perform.

Access roles
An access role categorizes users according to their job function. Each access group identifies one or
more access roles. Each access role represents how a set of users interacts with an application to
create and process cases.
Most applications allow one group of users to create and process cases, and a second group of users to
approve or reject those cases. For example, in an application for managing purchase requests, any
user can submit a purchase request, but only department managers can approve purchase requests.
Each group of users performs a specific role in processing and resolving the case.
For example, in an expense reporting application you want to allow employees to submit expense
reports, but not run reports. You define a role for employees, named Submitter, that allows users to
submit expense reports. Remember, each access role describes the capabilities of a specific set of
users.
KNOWLEDGE CHECK

What is the purpose of an access role?

The purpose of an access role is to identify the actions that a group of users can perform.

Privileges
A privilege is an authorization to perform an action. You grant privileges to an access role to deny,
allow, or conditionally allow actions to users.

314
©2018 Pegasystems
For example, consider a flow action to set a salary increase for an employee as part of their annual
review. The process for employee reviews routes all assignments to calculate a raise for an employee
to a common workbasket accessible by all employees in the Human Resources (HR) department.
However, you want to only allow HR partners assigned to a specific department to perform
assignments for employees in that department. So only an HR partner assigned to the Engineering
department can determine raises for employees in the Engineering department.
In this situation, applying the privilege conditionally allows you to test whether the HR partner is
assigned to the employee's department. If true, the HR partner can perform the action. Otherwise,
Pega denies the action to the user.
KNOWLEDGE CHECK

What is the role of a privilege in access control?

A privilege determines whether a user can perform a specific action. If the user has the privilege,
they can perform the action.

315
©2018 Pegasystems
Access control record types
When creating an application, the New Application wizard creates test users and access groups. These
test users represent the basic roles involved in case processing: users to create cases, and managers
to approve or reject them. For your applications, you may need to create additional roles with different
access control requirements.
Note: Starting with Pega Platform 7.4, the New Application wizard does not create users
automatically but instead displays a prompt to optionally add user names explicitly.
In Pega, you configure access control through a combination of record types: Access Role Name, Access
of Role to Object (ARO), Privilege, Access When, and Access Deny.

Access Role Name

An Access Role Name record describes a specific user role in the processing of cases. Pega uses an
Access Role Name record to associate an access group with a set of actions that users can perform.
Access Role Name records associated with an access group are listed on the Definition tab of the
access group record, in the Available roles section.
An access group can reference more than one role. When an access group lists more than one role,
Pega applies the settings for all the roles listed. For example, managers not only need to approve time-
off requests for their direct reports, but they also need to submit their own time-off requests for
approval. The Manager role identifies the actions that managers perform, such as approving cases. The
User role identifies actions that users perform, such as creating and editing cases. By listing both roles,
you allow members of the Managers access group to perform actions allowed for either role.
By applying more than one role to an access group, you can design modular, reusable roles and
combine those roles to meet complex security needs. If two or more roles conflict over whether to allow
or deny an action, Pega applies the most permissive setting across all the applied roles.
KNOWLEDGE CHECK

An access group lists two access roles. One role denies users the ability to run reports. The
other role allows users to run reports. Can members of the access group run reports?
Yes. When an access group lists more than one role, Pega applies the most permissive setting across
all of the listed roles.

Access of Role to Object

You use an Access of Role to Object record to define the access control settings for instances of a
specific class. Each Access of Role to Object identifies the set of actions that a role can perform on
instances of the specified class. For example, an Access of Role to Object named
PurchaseRequst:Administrators associated with a class that describes purchase request cases may allow
users to open cases, but not to run reports.

316
©2018 Pegasystems
Each Access of Role to Object record corresponds to a unique combination of access role and class. This
allows Pega to apply the permissions configured in the Access of Role to Object record to the users in a
particular role.
Tip: An Access of Role to Object record is sometimes informally referred to as an ARO.
KNOWLEDGE CHECK

The purpose of an Access of Role to Object record is ____________________________.

to configure the access control settings for a specific set of class instances for a specific access role

Privilege
Security needs sometimes require more granular control over elements of an application. For example,
you may need to prevent some users from running an approval process or performing a rejection
action. To allow or deny access to individual records, such as flow actions and correspondence, you
configure a privilege. For example, you add a privilege to a flow action to control which users can run
the flow action.
A privilege is a token. If a record requires a privilege, then users can use the record only if you grant
the privilege to a user role. A privilege record contains no information.

KNOWLEDGE CHECK

317
©2018 Pegasystems
 The purpose of a privilege record is _______________________________.
to manage access control for an individual record, such as flow or correspondence record

Access When
Some actions are only performed under certain situations. To test whether to allow or deny an action,
you configure a testable condition with an Access When record. At run time, Pega evaluates the
condition to determine whether users can perform the action.
For example, an employee evaluation case requires employees to provide a set of goals for the
upcoming year. At the end of the year, managers assess each employee's performance against the
goals listed for the employee. You want to restrict an employee from editing their goals unless the
evaluation case is in the Goal Setting stage. To do this, you create an Access When record to test the
current stage. If the current stage is Goal Setting, the employee can perform the action. Otherwise,
Pega denies the action to the user.
Note: Do not confuse When records with Access When records. Although both records consist of a
testable condition that evaluates to a Boolean result, only Access When records are used for configuring
access control.
KNOWLEDGE CHECK

The purpose of an Access When record is ____________________________________.

to define a testable condition, which is evaluated at run time to determine if an action is allowed or
denied to a user

Access Deny
By default, Pega denies access to all instances of a class unless you explicitly grant access to users. In
certain situations, government, or company regulations and policies sometimes require explicit denial
of access to specific capabilities. For example, government regulations on personally identifiable
information (PII) may require that a claims management application deny access to a patient's medical
information for anyone not directly involved in patient care.
To explicitly deny access to an action for instances of a class, you configure an Access Deny record. An
Access Deny record is similar to an Access of Role to Object record, but the logic is reversed. While the
Access of Role to Object record denies an action unless explicitly allowed, the Access Deny record allows
an action unless explicitly denied.

KNOWLEDGE CHECK

318
©2018 Pegasystems
 Why do you configure an Access Deny record, rather than denying an action on the Access of
Role to Object record?
You configure an Access Deny record to explicitly deny access to an action, often to meet government
or corporate regulations.

The following illustration shows the relationship between all these record types in managing access
control.

319
©2018 Pegasystems
How to manage access control
To simplify the configuration of security records, Pega provides the Access Manager. The Access
Manager presents you with an easy-to-use interface for managing application security. Navigate to the
Designer Studio menu and select Org & Security > Access Manager to open the Access Manager.

Manage access control with the Access Manager

The Access Manager provides three tabs for configuring security settings in an application.
l Use the Work & Process tab to configure access control for instances of a specific case type.
l Use the Tools tab to configure access to Pega tools such as the Clipboard and Live UI for end users.
l Use the Privileges tab to manage access to specific records, such as flow actions and
correspondence records.
The following screenshot shows the configuration for the HRApps:Administrators access group on the
Work & Process tab of the Access Manager.

To configure the access control for a setting, click the icon in the column for the appropriate role. The
Access Manager presents a pop-up window for you to select the level of access to grant — Full Access,
Conditional Access, or No Access.
Note: The Access Manager displays Conditional Access for a case type when you select different access
levels for the listed actions.

320
©2018 Pegasystems
Explicitly deny actions on class instances
The Access Manager manages the Access of Role to Object and Access Deny records for case types for a
selected access role. When you update a setting, the Access Manager updates the appropriate record.
Note: Access Deny records only manage actions on class instances, such as opening cases or running
reports. You cannot use an Access Deny record to explicitly deny access to tools or individual records.
An Access Deny record overrides an Access of Role to Object record applied to the same class and role.
Below the indicator icon, the Access Manager displays a link to the Access Deny record to indicate the
use of an Access Deny record. In the following example, the Access Manager indicates the use of an
Access Deny record to explicitly deny privileges to delete cases and run reports for the HRApps:User role.

For a description of each action, see the Help topic Case type authorization.
Important: The View History action applies to the class group, so the setting is the same for all case
types in a class group.
If necessary, the Access Manager creates Access of Role to Object records to reflect your configuration.
For example, when you create an application, Pega creates an Access of Role to Object record for the
class group. Any case types you create for the application inherit the settings for the class group. When
you update an access control setting for a specific case type, the Access Manager creates an Access of
Role to Object record for the corresponding class for the specified role.
Important: You must create an Access Deny record manually. The Access Manager creates only Access
of Role to Object records.

321
©2018 Pegasystems
Vary user access by system type
During development, you may want to configure more permissive access control to users to support
debugging. However, you want to configure more restrictive access control on a production system. You
can update individual Access of Role to Object and Access Deny records to automatically revoke access to
actions and tools as the application advances towards production.
An Access of Role to Object record grants access for action on a scale of 0 to 5. A zero means the action
is denied. The remaining ratings are compared to the production level value of your system. If the
privilege level is equal to or greater than the production level value of the system, Pega allows the
action. If not, Pega denies the action.
An Access Deny record denies access for an action on the same 0 to 5 scale. A zero means the action is
allowed. If the privilege level is equal to or greater than that the production level value of the system,
Pega denies the action. If not, Pega allows the action.
Production level values follow the software development life cycle. The greater the production level
value, the closer the system is to a production environment.

Production level Description

5 Production system
4 Preproduction system
3 Testing system
2 Development system
1 Experimental system

Note: For additional information on production level values, and how to set these values for the server,
see the Help topic System form - Completing the Production tab.
When you update an access control setting in the Access Manager, Pega updates the Access of Role to
Object or Access Deny record with a value of either 0 or 5. To apply a different value, click the access
role name in the Access Manager to open the Access Role Name record, then click the access class to
update the entry on the record.
Important: If you use access control levels other than 0 or 5, the Access Manager indicates the access
level on the current system. For example, you set the access control level to 2 (Development system)
for a role to delete instances of a case type. On a development system, the Access Manager indicates
Full Access. On a production system, the Access Manager indicates No Access.

Configure conditional access

To conditionally allow access to an action, tool, or privilege, you configure an Access When record.
Unlike numerical access control values, Access When records are not tested against the production level
of the system. If an Access When record returns a result of true, Pega grants access to the specified
action regardless of the production level of the system.
To conditionally grant or deny access, click the Indicator icon and select Conditional Access, then
enter the name of the Access When record. To create an Access When record, click the Crosshair icon to
the right of the field.

322
©2018 Pegasystems
You configure an Access When record as you do a When record. Create the when condition to evaluate
on the Conditions tab of the Access When record form. For instructions on configuring the when
condition of an Access When record, see the Help topic Access When form — Completing the
Conditions tab.

323
©2018 Pegasystems
How to add roles to an access control model
When you create an application, Pega provides a default access control model to support three
processing roles: users, managers, and administrators. In complex business processes, you may divide
these roles into more distinct roles. For example, an accounting application may reflect the following
roles for requests such as expense reports and purchase requests:
l Users — Employees who submit requests
l Managers — Employees who approve requests for direct and indirect reports
l Auditors — Employees who review requests for compliance with company policy
Each role requires that users perform different actions on a request. To ensure that users of an
application only perform the actions they are allowed to perform, you extend the access control model
by adding roles, then configuring the roles to allow or deny actions as appropriate.

Create a new role

You create a new role to customize access control for a specific set of users. For example, to
differentiate between employees who submit accounting requests and employees who process
requests, you define roles for each group of employees.
When extending the access control model with a new role, consider the following questions:
l What is the role of the user in processing a case?
l What actions do these users need to perform?
l How do these actions differ from the actions allowed for other users?
In Pega, you define an access role with an Access Role Name record, a label used to describe a specific
set of application users with a unique job function. You apply the role to Access of Role to Object and
Access Deny records to identify the actions allowed or denied to users assigned the role.

When you create a new access role, you must create a new set of Access of Role to Object records to
associate with the role. You can clone an existing access role to create a set of Access of Role to Object
records for a new role. Cloning an access role allows you to quickly create the needed Access of Role to
Object records. You then update these records as needed.
Tip: When cloning an access role, identify the most similar role currently defined on the system to
simplify configuration.
Note: When you create an application, Pega generates custom Access Role Name records by cloning
default records. For example, Pega creates an <ApplicationName>:Administrators role for each
application to manage security settings for developers. This role is a copy of the standard
PegaRULES:SysAdm4 role, which lists the default security settings for application developers.
Once you associate an Access of Role to Object record with an access role name, you can customize
privileges from the Access Role Name record. When you do, Pega applies your changes to the
corresponding Access of Role to Object record. To update an Access of Role to Object record, click the
entry in the Access Class column to open a modal dialog that displays the contents of the Access of Role
to Object record.

324
©2018 Pegasystems
Important: The Access Role Name record lists both Access of Role to Object records and Access Deny
records by class name. To identify the type of record listed, click the link.
After you create an Access Role Name record, you add the role to the appropriate access group. Pega
then applies the access control settings in the role to users upon log in. If necessary, create a new
access group to apply the role to the appropriate set of users.

325
©2018 Pegasystems
How to manage access to individual rules
In certain cases, you need to control access to specific user actions, such as individual flow actions. For
example, a bank organizes its account support agents into two roles: level one agents and level two
agents. Level one agents can respond to customer complaints and open an account dispute case. Only
level two agents can reverse a charge to an account to resolve an account dispute. In this situation, you
need to allow level two agents to perform the flow action to reverse the charge, but deny the action to
level one agents.
You create a Privilege record to control user access to a rule. When you add a privilege to a rule, users
can access the rule only if they are assigned a role that has been granted the privilege. When a user
attempts to use a rule with a privilege applied, Pega verifies whether the user is granted the privilege.
If the user is granted the privilege, Pega allows the user to use the rule. If the user does not have the
privilege, Pega denies the rule to the user.
To allow users to use a rule that references a privilege, you add the privilege to a user role. In the
previous example, to ensure that only level two agents can perform a charge reversal, you first apply a
privilege to the charge reversal flow action. Then you grant the privilege to the user role for level two
agents. Pega then denies the action to level one agents.

Create a privilege record

You create Privilege records to configure access control for specific rules, such as flows, flow actions,
and correspondence. Privilege records are listed in the +Create menu, under the Security category.
When naming the record, identify the action that the privilege governs. This helps other system
architects to select the correct privilege for other rules when configuring the access control model.
Caution: Whenever possible, save the privilege to the same class and ruleset as the rules that
reference the privilege. This reduces the likelihood that Pega denies access to a rule because of a
missing privilege.
Tip: When you create a privilege record, remember to complete the History tab. The contents of the
Full Description and Usage fields are displayed in the Access Manager. Use these fields to identify
the intent of the privilege and what rules require the privilege.

Require a privilege to use a rule

To add a required privilege to a rule, open the rule and list the privilege on the rule form. For most
rules that support privileges, you add privileges to the Security tab. For flow rules, you add privileges
to the Process tab. The following image shows a privilege applied to a flow action. At run time, Pega
verifies if the user has been granted the privilege RuleObjFlowAction:pyCascadingApprove before
allowing the user to perform the action.

326
©2018 Pegasystems
Grant a privilege to a role
You add a privilege to the user role on the Privileges tab of the Access Manager. In the Access
Manager, you can deny, explicitly grant, or conditionally grant a privilege to users. To conditionally
grant the privilege, you configure an Access When record to test when to grant and deny the privilege.
Tip: You can also configure the access control model to grant or deny privileges according to the
production level of the system. To do this, add the privilege to the role using the Access Manager, then
adjust the privilege setting on the Access of Role to Object record for the role and class.
The following example shows a set of privileges configured for the HRApps:Manager role. Users with the
HRApps:Manager role on their access group can use any rule that requires one of the listed privileges.

327
©2018 Pegasystems
To view the set of privileges granted to a role, select the role and class. To add a privilege to a role, add
the privilege to the table.
Tip: The Access Manager filters the class list to display either case types or data types. Under Type of
class, select either Case Type or Data Type to switch between a list of case types and a list of data
types.
By default, the Access Manager lists privileges applied to the selected class. To view inherited
privileges, select Show inherited privileges to display the privileges inherited from parent classes.
For example, you can define privileges in the class group to extend to all case types in your application.
These privileges are not displayed in the Access Manager unless you select Show inherited
privileges.

328
©2018 Pegasystems
How to manage user access with access
groups
In Pega, user access to an application is determined by the access group to which a user belongs. Each
access group references an application version that the user can access, and the roles that the user
belongs to when logged in. For each role in an application, you allow or deny actions and privileges to
determine what actions users assigned to the role can and cannot perform.
When you extend the access control model for an application, you may need to create additional access
groups to implement the entire model. When creating a new access group, consider how the access
group differs from existing access groups.
l Identify the application and application version for the access group.
l Identify allowed portals for user interaction.
l Identify allowed access roles for group members.
l Identify the cases that users can create.
If the access group you plan to create does not provide a unique combination of these factors, re-
evaluate the need for the access group.
Note: For best performance on a production environment, minimize the number of distinct access
groups in use on a system.
When you create a new access group, enter the access group name in the format
ApplicationName:JobDescription. For example, to create an access group for auditors for a Purchasing
application, use the name Purchasing:Auditors.
Tip: Before you create a new access group, review the access groups defined for the application.
Access group records are listed in the Records Explorer, under the Security category. If an existing
access group closely matches the needed configuration, you can save time and reduce configuration
errors by copying the access group and updating the configuration as needed. To create a copy of an
access group, open the access group record and click Save As, then enter a unique name.

Identify the application and application version for the

access group
Access groups specify the application that members can access. When configuring the access group,
identify the application and application version that users will use. This identifies the rulesets that are
added to the ruleset list for the user, which determines how users process cases.
To associate the access group with an application, enter the application name and version to the
Application section of the Definition tab of the access group record. The following example shows an
access group configured to allow users access to version 01.01.01 of the HRApps application.

329
©2018 Pegasystems
Note: If your application uses production rulesets, list the production rulesets used by the access
group on the Advanced tab of the access group record.
Consider creating a new access group when migrating users to a new application version for user
testing or as part of a phased roll-out of an application update. For example, when developing a new
minor version of an application, you may want to provide users with early access to the new version
without removing their access to the current version. This early access allows users to become familiar
with changes to the application, and allows users to provide feedback during development.
Since each access group can only reference one application, you need to create an additional access
group to allow users to access both application versions. You create a new access group to reference
the new application version, and add the access group to the operator ID record. Users can then switch
between the two access groups from the Operator menu.
Note: In Designer Studio, you switch between access groups from the Application menu.
If you need to migrate all members of the access group to a new application version, update the
application version on the Definition tab of the access group record rather than create a new access
group.

Identify allowed portals for user interaction

An access group specifies the portal or portals that members of the access group use to perform work.
Access groups for end users reference one of the standard end-user portals. When identifying portals
to add to an access group, select portals that align to the roles assigned to the access group. For
example, if members of an access group are managers, add the Manager portal to the access group
record. To add a portal to an access group record, list the portal in the Available portals section of the
Definition tab of the access group record.
When adding portals to an access group, identify a default portal to present to users upon log in. The
following example shows an access group configured to allow users access to the Manager and User
portals. In this configuration, Pega presents the Manager portal to members of the access group after
they log in.

330
©2018 Pegasystems
If an access group lists more than one portal, the remaining portals are available to users from the
Operator menu.
Note: In Designer Studio, additional portals are listed in the Launch menu, rather than the operator
menu. In Pega Express, additional portals are listed in the Application view menu.

Identify allowed access roles for group members

An access group identifies the access roles granted to members of the group. As you extend the access
control model for your application, you add new roles to an access group. Adding a role to an access
group grants the access control and privileges for the role to the user. To add an access role to an
access group, list the Access Role Name record in the Available roles section of the Definition tab of
the access group record.
When configuring an access group, identify the access roles that grant or deny privileges to match the
needs of members of the access group. An access group can reference more than one access role.
For example, an application allows employees to submit expense reports for reimbursement. The
application then assigns the case to the manager of the user for review. However, managers also
submit expense reports. So managers perform tasks associated with both the user and manager roles.
In this situation, you apply both roles to the access group for managers.
When an access group references more than one access role, Pega applies the most-permissive setting
across all the access roles.

Identify the cases that users can create

An access group identifies the types of cases that members of the group can create and process. To
identify the case types that members can create, you identify one or more work pools for the access
group on the Advanced tab of the access group record.

331
©2018 Pegasystems
A work pool is a set of case types a user can work on in an application. Each work pool corresponds to
a class group defined in the application or a built-on application. Users in an access group can only
create cases from class groups identified as a work pool for the access group. For example, Tom is a
member of the Users access group, while Mary is a member of the Managers access group. The
Managers access group lists a class group that contains the Transaction override case type, but the
Users access group does not. Mary can create a Transaction override case. Tom cannot create a
Transaction override case.
Note: If your application uses case types defined only in the Framework layer, add the class group for
the framework layer to the access group to allow users to create cases using case types defined in the
framework application.

332
©2018 Pegasystems
How to secure workbaskets and attachments
The Access Manager allows you to configure and manage access control settings for many of the
elements of an application. Security for two application elements cannot be configured in the Access
Manager: workbaskets and attachment categories.

Access control for workbaskets

In Pega, access control for workbaskets is role-based. By default, any user who can access a workbasket
can perform an assignment in the workbasket. To control whether users can perform assignments in a
specific workbasket, you apply one or more roles to it. When you apply a role to a workbasket, only
users assigned to a listed role may retrieve an assignment from the workbasket.
For example, the standard workbasket default@pega.com lists three roles. A user must be assigned the
PegaRULES:ProArch4, PegaRULES:Batch, or PegaRULES:Basics role to perform an assignment in the
default@pega.com workbasket.

Note: Pega uses the default@pega.com workbasket as a last resort for routing. Pega routes
assignments to the default@pega.com workbasket when no other more specific or local workbasket can
be found.
To apply a role to a workbasket, enter or select the role in the Roles section on the Workbasket tab of
the workbasket record.
Note: Do not confuse access control with skill-based routing. You prevent users from performing
specific assignments through the use of skill-based routing. You assign a role to a workbasket to
prevent unauthorized users from performing any assignment in the workbasket.

Access control for attachments

Pega provides two levels of access control for attachments. You apply a privilege or when condition to
an attachment category to allow or deny attachment actions to users. You enable attachment level
security to restrict access to the attachment itself.

Attachment category access control

Use a privilege or when condition to control access to an attachment category. When you add the
privilege, select the actions to allow if the user has the privilege. For each when condition, select the
actions to allow if the condition is true.

333
©2018 Pegasystems
Note: Configure access control for an attachment category using a When rule, not an Access When rule.
Users can perform an action on attachments in the category if they have at least one of the required
privileges, and all of the when conditions for the action are true. Consider the following configuration
for an attachment category.

Access control list by privilege

Privilege Create Edit View Delete Delete any
own
DeleteOthers x
DeleteOwn x
AdministerWorkbasket x x

Access control list by When Rule

When Create Edit View Delete Delete any
own
IsCurrentStageSubmit x x x

For this attachment category, the following conditions hold:

l Users can delete any attachment if they have either the DeleteOthers or AdministerWorkbasket
privilege.
l Users can delete their own attachment if they have either the DeleteOwn or AdministerWorkbasket
privilege.
l A user can create, edit, or view an attachment if the IsCurrentStageSubmit when rule returns a true
result.
Caution: If you use a When rule to control access to a category, deselecting an action is not sufficient to
deny access to the action. In the example above, the when rule IsCurrentStageSubmit is not sufficient to
prohibit users from deleting an attachment if the condition returns a value of false. For more
information, see the support article Access control 'When' rule does not affect Attachment Categories
on the PDN.
Tip: You can use the standard when rule Never to create an always-false condition to deny an action to
users.

Attachment-level access control

Configure attachment-level access control to allow users to determine who can access a specific
attachment within the category. When users add an attachment to the category, they identify one or
more work groups for which to allow access to the attachment.
To enable attachment-level access control, click the Enable attachment-level security check box on
the Security tab of the Attachment category record.

334
©2018 Pegasystems
 Creating agents for background
processing
Introduction to creating agents for
background processing
In this lesson, you learn how to create an agent for background processing. You also learn how to use
the System Management Application (SMA) and use DB Trace to trace and troubleshoot agents.
After this lesson, you should be able to:
l Explain the purpose of agents
l Describe agent types and modes
l Describe the agent processing model
l Define agents rules and agent schedules
l Create a standard agent
l Be able to trace and troubleshoot a standard agent

335
©2018 Pegasystems
Standard agents
An agent is a background process operating on the server that runs activities on a periodic basis.
Service levels, inbound messages (Services), and data flows are examples of agents running in the
background.
The assignment, queuing and management of background system operations is governed by agent
configuration. Agents route work according to the rules in your application. Agents perform system
tasks including:
l sending email notifications about assignments and outgoing correspondence
l generating updated indexes for the full-text search feature
l synchronizing caches across nodes in a multiple node system
The following video highlights how agents perform tasks in the background.
You can schedule agents to run at almost any time. For example, a case worker needs to check
currency exchange rates for an application that processes international transactions. The database
connection and currency retrieval can be done by an agent as a background task every five minutes.
The case worker continues processing the work item without stopping to look up the exchange rate.
The system retrieves the data in the background. If rapid updates were not needed , you could also
schedule the agent to process the currency lookup task at a specific time, for example, overnight.
Agents are autonomous and asynchronous. The activities they call run individually on their own
schedules. One activity does not have to finish before another one runs.
Typically, an agent can either be task-driven or schedule-driven.
Task-driven agents pick work from a queue. The queue entries are generally created during the work
item processing. For example, a case generates correspondence and an agent sends it.
Schedule-driven agents directly run an activity to perform their tasks. For example, every morning an
agent runs the system cleaner to clean up temporary database entries. A queue entry is not needed
before the agent runs this operation.
KNOWLEDGE CHECK

The __________ agents pick their work from a queue.

task-driven

336
©2018 Pegasystems
How to perform background processing with
an agent
When an agent starts, a master agent creates an agent thread and associates it with a requestor. A
Pega master agent checks the agent's queue for entries. If there are no entries, the agent stops without
running the agent. If the system finds one or more entries in the queue, the system retrieves and locks
the entry, and then starts the agent activity. The activity processes the entries and stops when the
maximum number of entries (that you define) have been processed, or until the queue is empty —
whichever comes first. The agent starts again at the specified interval.
Note: For a description of master agents, see the Help topic master agents.
You add agents to an agents rule. An agents rule provides a template that specifies the global settings
for agents on all nodes. An agents rule is not itself an agent. Agents rules are instances of the Rule-
Agent-Queue class in the SysAdmin category.
Note: A ruleset can have only one agents rule.
For each agent in the agents rule, you specify:
l Whether to enable or disable the agent
l Which activity the agent will run
l The maximum number of entries the activity will process before the agent stops
l The schedule that controls when the agent will start and run the activity. You can specify one of
three schedule patterns:
A periodic interval measured in seconds, such as every 180 seconds.
A recurring time interval that defines a start time and schedule, such as 12 A.M. every Friday.
Once at startup, based on a specified parameter.
l The way the agent interacts with the queue when running an activity.
You typically run the agent in standard queue mode. In this mode, Pega manages the agent queue
functionality. The activity does not perform transaction tasks such as getting a lock on the entry or
committing the changes to the database. The agent activity contains only business logic.
l Whether you enable Auto Queue Manager (AQM)
AQM manages the state of each agent queue entry as it is moves from the scheduled agent queue
through agent processing. AQM also controls how a queue entry is retrieved for processing. This
includes locking and updating the state of the entry. For each entry, if agent processing succeeds,
all entries are committed to the database. If agent processing throws an exception, then the system
rolls back all entries associated with that operation. AQM then moves the entries to the Broken
Process queue. You can troubleshoot entries by monitoring entries in that queue.
As shown in the following example, an agent sends correspondence to customers approved for
loans.
1. Correspondence entries wait in the scheduled queue until the agent activity starts.
2. AQM locks the entry and sends it to the agent activity for processing.

337
©2018 Pegasystems
 3. If processing is successful, the correspondence entries are sent. If processing fails, the entries
are sent to the Broken Process queue for troubleshooting.

For more information about queue modes and AQM, see the PDN article How Agent Queues Work.
KNOWLEDGE CHECK

Under what conditions does an agent activity stop processing (assuming there are no
errors)?
An agent activity stops processing when all the items in the scheduled queue have been processed
or when the number of entries reaches the maximum defined in the agents rule.

Agent schedules
When you create an agents rule, a Pega master agent generates one agent schedule data instance for
each server node running on your Pega system. Agent schedules are data instances of the Data-Agent-
Queue class in the SysAdmin category. You do not create or copy agent schedules. The system must
create agent schedules in order to associate them with an agents rule.
Agent schedules determine whether an agent is enabled, and on which server node that agent will
run. A new agent schedule contains the schedule intervals and the enable setting you specified in the
agents rule. The master agent uses the settings in the agent schedules when checking for agents. The
master agent does not use the settings in the agents rule. Therefore, if necessary, make updates to the
schedule or enable/disable the agent in the agent schedule. Be careful to make these changes to each
agent schedule on every node. This ensures that the agent functionality is consistent across nodes in
the system.

338
©2018 Pegasystems
To modify the settings on an agent schedule, on the Agents rule form, select a node displayed on the
Nodes tab to open its agent schedule.

Pega provides standard agents rules. These agents rules are in locked rulesets so you cannot modify
them. To change the configuration settings for the agents listed in these rules, update the agent
schedules generated from the agents rule.

Notes: For information about standard agents rules, see the Help topic Atlas - Standard Agents.
For more information on how agents process items, see the PDN article Overview of agent processing.
KNOWLEDGE CHECK

When the master agent checks for agents, which agent schedule settings does the master
agent use?
The master agent uses the schedule settings in the agent schedule instance.

Creating agents or defining schedule intervals

For instructions on how to create an agent or how to configure agent schedules, see the PDN articles
How to create an agent and Agent schedule intervals.
Note: The procedures in the PDN articles were created in Pega 5.4. The styles on the rule forms have
been upgraded in Pega 7. However, the fields and functions are still applicable.

339
©2018 Pegasystems
How to troubleshoot issues with agents
Agents can fail to correctly process items for different reasons. For example, agents cannot locate
assignments they are attempting to process, or the agents are unable to obtain a lock on an entry
because they lack security access.
You have two options available when troubleshooting issues with agents. These options are available
in Pega Platform through either the System Operations landing page or the System Management
Application (SMA).
l Examine items in the Broken Process queue
l Trace running agents using the Tracer tool

Checking the Broken Process queue

If processing fails, all the changes are rolled back. If Auto Queue Management (AQM) is enabled and
the system cannot commit a queue entry, AQM puts the entry into failure status and stores the entry
into the Broken Process queue. From there, users who hold the @baseclass.ReconcileBrokenQueueItems
privilege can view the issue, fix it, and resubmit or delete the broken queue entry.
Important: Enable Auto Queue Management (AQM) as a best practice. If it is disabled, when an entry
is retrieved for processing, the system removes the task from the queue. If processing fails, that entry
is lost and cannot be restarted in the Broken Process queue.

Tracing running agents

You can use the Tracer tool to troubleshoot agents while they are running. Tracing agents allows you to
examine issues such as failed activity steps that may be preventing the agent from committing an
entry. You can trace agent processing throughout the system. This enables you to troubleshoot agents
even if AQM does not add failed entries in the Broken Process queue. When you trace an agent, SMA
lets you control when to start the agent and when to run the tracer.
KNOWLEDGE CHECK

If AQM is enabled, what happens when agent processing fails?

All changes are rolled back and the entries are sent to the Broken Process queue.

Troubleshooting agent processing

The System Operations landing page provides information about the status of agent processing within
the system. From Designer Studio, click System > Operations to open the System Operations landing
page.
The Agent Management tab lists the agents configured for the system. For each agent, the landing
page displays the status of the agent. If Pega Platform is deployed to a cluster of systems, the landing
page displays the status of the agent across all nodes in the cluster.

340
©2018 Pegasystems
The Agent Management tab is divided into three tabs.
l Use the Cluster tab to manage agent execution across all nodes in the cluster. The tab indicates the
status of each agent on all nodes in the cluster. On the Cluster tab, you can click the agent name to
open the agents record used to configure the agent.
l Use the Node tab to manage agent execution on a single node. The tab indicates the status of the
agent on the selected node, and the time the agent last ran on the node. On the Node tab, you can
click the agent name to open the agent schedule configured for the node. To select a different node
in the cluster, click the down arrow to the right of the node ID.
l Use the Notification settings tab to configure Pega Platform to send email notifications when
execution of an agent fails.
To manage execution of an agent, select the agent using the check box to the left of the agent name.
Then use the buttons above the list of agents to start or stop the agent, restart the agent, and trace
agent execution.
Tip: When you trace agent execution, use the Trace next run or Trace next earliest run options if
the agent is scheduled to run in the next 30 minutes. Each option automatically starts the Tracer when
the agent runs. Otherwise, use the Trace now option to trace agent execution. For more information
on tracing agent execution, see the Help topic Tracing agents.
The Queue Management tab displays the agent processing queues used by Pega Platform to monitor
agent processing. Pega Platform represents each queue with a tile displayed at the top of the landing
page. When you select a tile, the landing page displays the items in that queue. For example, click the
Broken tile to view the contents of the Broken Process queue.

341
©2018 Pegasystems
Select an item in a queue to remove the item from the queue.
Tip: Click the arrow icon on the Remove button to remove all items in the queue.
To defer items in the Scheduled and Immediate queues, select the item and click Defer. To requeue
items in the Broken Process queue, select the item and click Requeue.

Troubleshooting agents with the System Management Application

Note: The System Management Application is used to manage and troubleshoot agent execution for
installations of Pega Platform prior to version 7.2.2. Starting with 7.3, developers should use the
System Operations landing page, especially on cloud deployments.
The System Management Application (SMA) gives you access to a list of items in the Broken Process
queue. SMA also gives you access to the Tracer tool so that you can monitor a running agent. Open
SMA in Designer Studio > Systems > Operations > System Management Application.
The following demonstration first shows you how to locate and manage items in the Broken Process
queue. Then the demonstration shows you how to identify issues by tracing a running agent.
Note: The style of the agent schedule rule form shown in the video has been upgraded in Pega 7.
However, the fields and functions are still applicable.
You can administer broken queue items using the Broken Queue Items report. Select Designer Studio
> Process & Rules > Tools > Work Admin > Broken Queue Items to access the report. For
instructions on how to use the tool, see the PDN article How to requeue failed agent items with the
Broken Queue Items report.
Note: For more information about identifying and correcting agent issues, see the PDN article
Troubleshooting agents.

342
©2018 Pegasystems
 Migrating an application
Introduction to migrating an application
An application is typically packaged and exported to move it to another system. For example, you
package and export an application to migrate among development, testing, and production
environments. In this lesson, you learn about the features and tools available to package, export, and
import applications.
After this lesson, you should be able to:
l Describe the purpose of a product rule
l Associate data objects with a ruleset
l Describe the contents of the product rule
l Create a product rule with the Application Packaging wizard
l Generate an application archive
l Import an application archive

343
©2018 Pegasystems
Product rule
Applications consist of rulesets, application data, system data, and other objects such as database
schemas. As an application moves toward production, the application and its components must
migrate among Pega systems. For example, after you have completed development, you migrate the
application from the development environment to a QA environment. In some cases, you may want to
migrate only specific application components such as updated rulesets or data objects that are
included in a patch release.
Imagine that you are moving from one house to another house. You would likely create a manifest of
household items you want to move. You would not include things like cabinets, plumbing, or wiring.
Those items are already built into the house you are moving to. You would then load the items on the
manifest into a moving van. When the van reaches its destination, the items are taken out of the van
and unpacked in the house.
Like the manifest described in the previous example, you create a product rule that identifies the
application components you want to move to a destination Pega system. A product rule lists the
rulesets, data, and other objects that make up an application. The product rule usually does not
include standard rulesets and data because those components are built into all Pega systems. A
product rule is an instance of the Rule-Admin-Product class, and is sometimes referred to as a RAP. You
can find product rules in the SysAdmin category in the Records explorer.
Like you would load the moving van, you put the contents of the product rule into a ZIP archive file
(sometimes called a RAP file). The information consists entirely of XML documents in Unicode
characters. You copy the archive file to the destination system and import the file's contents into the
system.
You can create a product rule directly in the rule form. Alternatively, Pega provides a tool called the
Application Packaging wizard that guides you through the creation of a product rule in a series of
steps. Both approaches allow you to generate the archive file.
The following video highlights the basics of application migration.
KNOWLEDGE CHECK

In order to migrate an application between system environments, what actions must you
perform?
First, identify the application components in a product rule. Then put the rule contents in an archive
file. Finally, copy the archive file to the destination system and import the file.

344
©2018 Pegasystems
How to create an application archive file
To create an application archive file, you must first create a product rule to identify the components
you want to include in the archive file. Then, you create an archive file that contains the application
components.

Create a product rule

You can create a product rule in two ways:
l Create the rule instance manually and add the information to the fields on the rule form. The rule
form provides greater flexibility than the wizard. For example, you can set minimum or maximum
ruleset versions to include in the archive rule. You can also include rulesets that are not in the
application. However, manually entering information — such as selecting specific data instances —
can be time-consuming and error-prone.
l Use the Application Packaging wizard — it guides you through a series of steps that populate and
create a product rule. The wizard includes the rulesets in your application. Because the wizard
presents an inventory of components that are in your application, selecting the components you
want to include is easier and more accurate than manually entering them in the product rule. When
the wizard creates the product rule, it enters your selections automatically on the form. For finer
control, you can modify the product rule after you have created it in the wizard.

Create an archive file

Before you create an archive file, do the following things to ensure that the file is complete and correct:
l Associate your data records with rulesets. This ensures that all the data records required by your
application are included in the archive file.
l Make sure that all rules are checked in so that the rulesets are complete and current.
l In most cases, lock the application rulesets included in the package. This helps ensure that the
migrated application and its rulesets are synchronized among the source and destination systems.
l If you are exporting the application to a production system, you should merge branched rulesets
and remove the branches from the application.
Note: Do not lock delegated rulesets. Locking the rulesets prevents users from updating the rules
in the destination system.
You can create an archive file using buttons on the product rule form or on the landing page that
contains the wizard.

345
©2018 Pegasystems
How to associate data instances with rulesets
Associating data instances to a ruleset simplifies application migration and maintenance. When you
package an application for migration, you include an application's rulesets. However, a ruleset
corresponds to a collection of rules, and does not include data instances such as operator IDs, access
groups, database tables, and databases.
To help make packaging and migration of data instances easier, you associate data instances with
rulesets. By doing this, you do not need to specify each data instance in the product rule. When you
create the product rule, the system adds the data instances to the archive file automatically.
As a best practice, associate data instances with rulesets. As you create data instances of certain
classes, either manually or with a wizard, the system automatically associates the instance with one of
the application's rulesets.
The associated ruleset appears in the rule header. The following example provides an access group
that is associated with the Purchasing ruleset. You can change the associated ruleset by clicking Edit.
Update the ruleset in the Associated RuleSet pop-up dialog.

You can remove the ruleset so that the data instance is not associated with any ruleset. For example,
you may not want to associate specific instances of operator IDs that you do not want to export.
Removing the associated ruleset results in a guardrail warning.

Associating a data instance with a ruleset does not affect or restrict any run-time behavior. The data
instance remains available to all applications regardless of the associated ruleset.

346
©2018 Pegasystems
How to configure a product rule
You define the application components you want to package in a product rule. Put the product rule in
the same ruleset as the work class for the application.

Identifying the components

You specify the components you want to export on the Contents tab of a product rule. The tab includes
these sections:
l Applications to include
l Rulesets to include
l Class instances to include
l Individual instances to include
l JAR files to include
l File details
For more information about the settings on the product rule Contents tab, see the help topic Product
rules - Completing the Contents tab.

Applications to include
Specify the application rules that identify the rulesets and versions to include in the archive file. Using
this option eliminates the need to specify the individual rulesets and versions in the RuleSets to
includesection. Select the application in the Name and Version fields. The order of applications in
the array is not important.

Rulesets included in the archive must have all the prerequisite rulesets included either in the product
rule or on the destination system. When the product rule is exported to an archive file, the archive
contains information about all the rulesets associated with the application. This information is used by
the Import wizard to warn you about missing rulesets on the destination system.
A ruleset using Application Validation (AV) mode has no prerequisites. Rules within a ruleset using AV
mode can refer to rules in any rulesets in the application and its built-on application. An AV ruleset,
therefore, should be exported within the context of an application.
Use the following settings to automatically include specific components or patch ruleset versions in the
archive.
l Select Include associated data to automatically export any data instances associated with the
application ruleset. Instances selected in the Individual instances to include section are not used.
Typically, these data instances are derived from the Data- class and include operator ID, access

347
©2018 Pegasystems
 group, database table, and database records.
l Select Custom/Production rulesets to automatically include the production rulesets listed on the
application rule. You should select this check box if you are using delegated or localization rulesets
(these are production rulesets).
l Select Include rule history to include the instances of History-Rule class. The instances are rows in
the standard history rule table. These instances include the date, time, operator, and comments in a
rule's History tab that are added when a developer checks in a rule. This information can be useful
for auditing purposes when migrating applications to another development or testing environment.
l Select Include data types to include the instances of the custom data types (classes) that you have
created for your application. For example, you may have created a Customer data type to manage
customer contact information. This data type might include information such as customer's name,
email, or phone number. The data types are exported even if they are not associated with a ruleset.
l Select Delta mode to include only the highest patch version of the application's rulesets in the
archive file. For example, if your application references OrderEntry:02-03-05, the archive file
produced from the product rule includes only rules in OrderEntry:02-03-05. This feature is useful
when you are migrating a patch update and do not want to include the contents of all the
prerequisite rulesets.

Rulesets to include
Specify rulesets that are not part of an application. The rulesets can be entered in any order. During
import, the system determines a valid order to load the rules. Make sure that the prerequisites are
included in the list or already exist on the target system. For example, when you include rulesets from
other applications, you must verify that all the prerequisites are listed in the product rule or are
already present on the target system. If the prerequisites are not present on the target system, some
rules may be unavailable.

l Use the Minimum version and Maximum version fields to define a range within a major version
that you want to include in the product. Leave both fields blank to include all versions.
l Select Exclude non-versioned rules to exclude rule types that are associated with a ruleset but
not with a version, such as class and application rules.
l Select the Include associated data check box to include data instances associated with the
selected rulesets.

Class instances to include

You can include all instances from any class by entering a class name. In addition to concrete classes,
you can enter an abstract class that has concrete subclasses. This section is useful for specifying data
classes (derived from the Data- base class) that are required for an application to run correctly on the
destination system. Remember that if you have selected the Include associated data check box in the
Applications to include section or RuleSets to include section, all data instances associated with the
rulesets are exported by default.

348
©2018 Pegasystems
Be careful to note any dependencies among data instances or between data instances and your rules.
During import to the destination system, data instances already present are by default not overwritten.
These data instances may require adjustment after they are imported.

You can use a when rule in the When filter field to filter the class instances you want include in the
ZIP file. The ListView filter column is included for backward compatibility.
If you select Include descendants?, all the subclass instances are included and the ListView filter
and When filter values are ignored.
Use the Exclude classes field to enter the names of descendant classes you do not want to include.
You can enter more than one class using a comma (,) to delimit the names.

Individual instances to include

Complete this optional array by listing the specific class instances that you want to include in the
archive file. For example, you may want to include only specific operators or access groups in the
product rule, rather than all instances.
Note: If you select Include associated data in the Applications to include section or RuleSets to
include section, your selections are ignored if the instances are associated with application rulesets.
Instances are processed in the order listed on the product rule. This is important if your application
includes views that reference each other. Listing the instances in the wrong order can create
dependency tree errors. Drag and drop the instances to change the order.

349
©2018 Pegasystems
As a best practice, when selecting large numbers of instances, use a filter in the Class instance to
include section.

JAR files to include

The Pega 7 Platform allows you to extend the Java code built into the Pega 7 platform with your own
code. The code can be used with activities (Rule-Obj-Activity rule type), user interfaces, or system
interfaces. If your application uses JAR files, complete the array in the Jar files to include section to
include JAR files in the product archive.

To locate available JAR files, enter a class name in the Search jar files field and click Query jars.

350
©2018 Pegasystems
File details
Use this section to prepare the product rule for packaging in a ZIP archive file.
The date in the Creation Date field displays on the destination system before the archive file is
imported. The date value entered persists even when the file is copied or renamed. Enter a text
description of the contents of this file in the Short Description field. This value appears on the
destination system before the archive file is imported.

As a best practice, lock the ruleset versions you are including in the archive file. This helps prevent
updates to the rulesets after they have been packaged in the archive file. Select Allow unlocked
ruleset versions? if you want to include unlocked ruleset versions. For example, select the check box if
you are including a delegated ruleset.
If you want to include post-import instructions such as a Read-Me text, identify an HTML rule on the
Installation tab. The file is displayed at the end of the import operation for this product rule.
The Preview Product File button lets you review the contents of the product definition before
creating the archive file. It is a best practice to review contents before you create the archive file to
ensure that the contents are correct.
The Create Product File button creates an archive file on your local computer.

351
©2018 Pegasystems
Exporting an application using the
Application Packaging wizard
The Application Packaging wizard simplifies the process of exporting an application by guiding you
through the steps to create a product rule. In each step, you add the application components you want
to include. After you complete the steps, the wizard creates the product rule. You can then review the
product rule contents and generate the archive file.
Follow these steps to create a product rule and generate an archive file:
1. Start the wizard by selecting Designer Studio > Application > Distribution > Package.
2. On the Application step, use the Application drop-down to select the application you want to
package. The drop-down contains the applications you have access to on the current system.
3. In the Ruleset Name and RuleSet version fields, select the ruleset and unlocked version that
contain the product rule. If you specify a locked ruleset, you receive an error message.
4. Optionally, click Check to display only Application Rulesets to display the rulesets specified in the
selected application's rule form. If unchecked, only rulesets in your ruleset stack, as shown on your
operator profile, are displayed.

As you proceed through the steps in the wizard, the system automatically lists the components that
are available in your application with a check box. Components that are used by your application
are selected by default. If you want to exclude a component, deselect the check box

352
©2018 Pegasystems
5. On the Application Stack step, identify the chain of built-on applications ending with the base
PegaRULES application. Depending on the applications present on the destination system, you may
not need to include the entire stack in your package.

6. On the Application Dependencies step, identify the products that many Pega-supplied applications
are dependent on. The Pega 7 Platform verifies that these dependencies are installed on the
destination system before importing the Pega-supplied applications. If there are no required
products for your Pega-supplied applications, skip this task.
7. On the Organizational Elements step, identify the organization, divisions, and units associated with
your application.

8. On the Access Groups step, identify the access groups associated with your application. If you have
created access groups for the purpose of development or testing and are not part of the application,
clear the check box next to the access group names to exclude them.

353
©2018 Pegasystems
9. On the Operators step, identify the operators associated with the application. If you have created
operators for the purpose of development or testing and are not part of the application, clear the
check box next to the operator names to exclude them.

354
©2018 Pegasystems
10. On the Work baskets step, identify the work baskets associated with your application.

11. On the Work Groups step, identify the work groups associated with your application.

12. On the Data Tables step, identify the local data storage data types used in the application. A link
named No Connection is displayed in the Count column if a connection issue arises. For example,
an external data table may have more than one data class mapped to it. Click the No Connection
link to open the rule, and click Test Connection to identify the issue.

13. On the Database Storage step, identify the databases and database tables that are available to your
application.

355
©2018 Pegasystems
14. On the Code Archives step, identify the java code archives used by your application.
15. On the Integration Resources step, identify the integration resources available to your application.
The integration instances associated with your application are automatically selected.

When you have completed all the steps, click Finish. The system creates the product rule in the
ruleset you specified. The wizard names the product rule after the application you specified. The
version is set to the date and time it was created.

356
©2018 Pegasystems
 After you click Finish, the Package landing page displays a dialog that lets you perform various
tasks.

16. You can do the following:

l Click Preview to show the content of the ZIP file that is created by the product file.
l Click Modify to open the product rule so that you can manually add or remove instances or change
default settings.
l Click Migrate to start the Product Migration wizard. The Product Migration wizard lets you
automatically archive, migrate, and import a Product rule to one or more destination systems. For
more information on exporting an application with the Application Packaging Wizard, see the Help
topic Product migration.
l Click Export to create an archive file on your local computer. The system displays a Create Product
File dialog in which you enter a file name.

Click OK. A progress indicator is displayed. When the export process is complete, the indicator
displays a link to the archive file.
Click the link to download the file.

357
©2018 Pegasystems
 Note: After you have created your product rule, you can also create the archive file using the Export
gadget. The gadget is available from Designer Studio menu by selecting Application > Distribution
> Export. In the gadget, provide the product information and click Perform export. You can also
use the Export gadget to quickly package specific rulesets and data objects without having to create
a product rule.

Updating the product rule after you use the wizard

The product rule created by the wizard uses default settings that you may have to override, depending
on your requirements or selections you made in the wizard. Click Modify to open the rule and make
your updates.

What you want to export Where to make the update

You are exporting delegated rulesets. In the File details section, select the Allow
unlocked ruleset versions? check box. These
rulesets must be unlocked so that users can
access them on the destination system.

In the Applications to include section, select

the Custom/Production rulesets check box.
You have excluded specific associated data In the Applications to include section, clear the
instances in the wizard. Include associated data items check box.
Otherwise, all associated data items are included
in the archive file.
You have excluded specific data tables in the In the Applications to include section, clear the
wizard. Include data types check box. Otherwise, all
data types are included in the archive file.
You do not want to include rule history instances. In the Applications to include section, clear the
Include rule history check box.

358
©2018 Pegasystems
Importing an application archive
Use the Import gadget to import the contents of an archive on the destination system. You must have
the @baseclass.zipMoveImport privilege to use the Import gadget. Rules, data, and other Pega system
instances contained in the archive file are added to the rules already present in this system, optionally
overwriting some existing rules.
For more information, see the help topic Importing a file by using the Import wizard.
1. On a destination system, open the Application Import wizard from Designer Studio > Application >
Distribution > Import.
2. Select the archive to upload. Choose to import a local file, import a file from a repository, or specify a
file that already exists on the server.
Note: If you choose to import a file from a repository, you must specify the Repository name,
Artifact type, and artifact Name.
Note: By default, uploading a file larger than 1 GB is not possible. For larger files, use File Transfer
Protocol (FTP) or another means to place the file into the ServiceExport directory.

3. Optional: Click Show content details to show the details of the contents.
4. Optional: Select the Enable advanced mode to provide more granular control over the import
process check box to include or ignore individual instances. If you do not select this option,
continue to step 7.
5. Optional: Select the Do not set restore point or save metadata during the import check box.
Tip: When you import an application archive, you can set a restore point to roll back the import to.
Selecting this check box will limit import time, but means you cannot roll back to the current state
of your system. For more information on restore points, see the help topic Restore points.
6. Click Next and continue through the pages to review or edit instances that are skipped, inserted,
replaced, or added. When you reach the last page, the import starts.

359
©2018 Pegasystems
7. Click Next to start the import. The system attempts to upload the rules in an order that minimizes
processing. When complete, the progress indicator displays 100.00%.

8. After processing is complete, adjust access groups or application rules to provide access to the new
rulesets, versions, and class groups as needed.

When imported rules are available

If you import rules in a ruleset that users can already access, the rules may begin executing
immediately. These rules may execute before all the rules in the same archive have been imported.
Similarly, declarative rules begin executing immediately. This means that the declarative processes
might fail if the elements or properties they reference have not yet been uploaded. This needs to be
planned for when an archive is imported on a system with active users.

360
©2018 Pegasystems
COURSE SUMMARY

361
©2018 Pegasystems
 Next steps for Senior System
Architects
Senior System Architect summary
Now that you have completed this course, you should be able to:
l Identify the tasks and responsibilities of the senior system architect on a Pega Implementation
l Create and extend a Pega application
l Manage rules and rulesets
l Leverage the Enterprise Class Structure (ECS) to promote rule reuse between case types and
applications
l Configure roles, access groups, and privileges
l Manage data access within an application
l Create wizards to configure a sequence of assignments
l Design applications for multiple device types and screen sizes, including mobile devices
l Manage integration settings

Next steps
Completion of Senior System Architect helps to prepare students to take the Certified Senior
System Architect exam.
Join the Pega Community at community.pega.com to find information to successfully implement a
Pega solution.

If you want to learn about Pega Applications, visit Pega Academy.

362
©2018 Pegasystems